Offical Website

[philsturgeon]

Who wants the job of making the documentation for the website?

Instructions here

[scottrobertson]

Once we decide on and implement #66 I shall do it.

[scottrobertson]

Why can't we just use Jekyll :( all this coping folders around and stuff is awful.

[scottrobertson]

Also, Sculpin does not work. When i generate, all of the *.html files are totally empty.

[philsturgeon]

It sounds to me like you are doing it wrong. Hop on IRC sometime and lets see if you can get some help from @reinink.

It's a nice smooth process as far as I'm concerned. :)

[scottrobertson]

Regarding my first message, its to do with https://github.com/thephpleague/thephpleague.github.com/tree/project-website-theme#how-to-publish (awful)

Second part, I am just running sculpin generate and all the files are there, but empty.

[philsturgeon]

That is literally one piece of setup with a bit of advice on a good way to do things. Sculpin is basically missing a rake deploy equivalent and you need to do that yourself, but of course as we are smart budding developers we can do that sort of thing ourselves.

https://github.com/thephpleague/fractal/blob/sculpin/deploy.sh

Identical to rake deploy. I just enter my github credentials after its built and the job is done. 

Copy that, tweak it as you need and I’ll update the how to page.

[scottrobertson]

Ok, thanks.

I just prefer being able to just push 'gh-pages' repo and it just builds it all it's self haha.

[reinink]

I can appreciate that the publishing process feels a little painful. What you see in those instructions is the simplest possible instructions I could come up with, other than actually creating a deploy script as Phil is suggesting. We decided to use Sculpin because, 1. it's a PHP project, and 2. it supports themes.

[reinink]

Also, Sculpin does not work. When i generate, all of the *.html files are totally empty.

That clearly is not right. I wonder if there have potentially been some updates to Sculpin that are breaking things. I'm going to have to do some testing to confirm.

[scottrobertson]

I can appreciate that the publishing process feels a little painful. What you see in those instructions is the simplest possible instructions I could come up with, other than actually creating a deploy script as Phil is suggesting. We decided to use Sculpin because, 1. it's a PHP project, and 2. it supports themes.

Makes total sense

That clearly is not right. I wonder if there have potentially been some updates to Sculpin that are breaking things. I'm going to have to do some testing to confirm.

Thank you. I shall try remove and install it all again when i get home. I was going to try a different php version etc too just to make sure.

[reinink]

Okay, so I was able to reproduce the blank pages when I did not run sculpin install prior to starting the server (sculpin generate --watch --server). Can you confirm that you've run this?

You can tell if sculpin install has been run if there is a .sculpin folder. There will also be a /source/themes/ folder created.

[GrahamCampbell]

I've generated some api docs here: http://muffin.grahamjcampbell.co.uk/. I've included the faker library in the generation. Also, I've excluded all the tests.

What do you guys think? Also, sami isn't generating the @method docs correctly? Can anybody confirm that the static @method docs work for them in their ide?

[scottrobertson]

Can you confirm that you've run this?

@reinink I did yeah. I shall check if folder exists when I get back home.

I've included the faker library in the generation. Also, I've excluded all the tests.

@GrahamCampbell I am not sure we need to include their stuff do we?

[GrahamCampbell]

We don't have to, no. I can remove it if you like?

[scottrobertson]

That is totally up to you :) it was just my opinion.

[GrahamCampbell]

I'll ditch them. It's way faster to generate without them. :)

[GrahamCampbell]

http://muffin.grahamjcampbell.co.uk/

You might need to hit crtl + f5 to see the changes.

[GrahamCampbell]

What do you want to do about these api docs?

[scottrobertson]

I could have a go sometime, but I am not going to have time tonight/tomorrow.

[GrahamCampbell]

I was asking about the "api docs". As in, those auto-generated ones.

[GrahamCampbell]

Do we want to make the offical, maybe change the url?

[scottrobertson]

Ohh right ok. I'm not sure what we should do with them. Not sure what the process around hosting them is etc.

[GrahamCampbell]

Well, we could use github pages, or just leave them on my droplet. I can't imagine them using much resources.

[scottrobertson]

Not sure how we could use github pages, as gh-pages branch will be used by the docs

[GrahamCampbell]

We could make a new repo anywhere. Github pages allows custom urls.

[GrahamCampbell]

See #193. This stuff can easily be added to a website too.

//cc @philsturgeon, @scottrobertson

[GrahamCampbell]

Ping @scottrobertson. Have you made any progress with the website? Are we still good for a release on Thursday, or do you need some more time?

[scottrobertson]

@GrahamCampbell sadly not no. I have had literally no time at all sorry.

[GrahamCampbell]

Don't worry about it. We can always just make the gh-pages branch the api docs for now? Shall I make that change?

[scottrobertson]

Naa, there is not really much point. The README is pretty awesome right now, just need to find some time to move it to the actual site.

[GrahamCampbell]

But we need a website before we launch like the other league repos. Also, I don't think we should "move" the documentation over there - just duplicate it, like the flysystem repo does.

[scottrobertson]

Having API docs is nothing like the other websites though. I just don't see much point as it won't help the average user learn anything they can't learn from looking at the code.

It's up to you though, I am willing to do whatever. Apologies for not having time though.

@philsturgeon what do you think?

[GrahamCampbell]

I'm not saying we need api docs, i'm saying we need a website. I was suggesting dumping those on there is a quick fix for now.

[scottrobertson]

We only need a website to serve a purpose though don't we? Having a placeholder for the sake of having a website seems pointless to me when the README does a better job.

[scottrobertson]

I shall try and find some time tonight :)

[GrahamCampbell]

TBH, I don't really like the idea of having a website anyway. I'm only pushing it because I think we have to as a php league repo. What's the reality of this @philsturgeon?

[scottrobertson]

Yeah, I am kinda the same.

It does make sense to have it there for documentation and stuff, but I am not sure it should be a blocker for v2

[GrahamCampbell]

I'm not sure it even makes sense to have it anyway. For example, if you look at flysystem's - all that's happened is it has become outdated because it's a pain in the ass to update. It'd prefer just to maintain our readme and upgrading guide as they are now.

[philsturgeon]

It's not a requirement and it's not a blocker for v2. Get v2 out then try and get a website done at some point if you want.

---Sent from Boxer | http://getboxer.com

On 5 August 2014 16:17:45 GMT-4, Graham Campbell notifications@github.com wrote:TBH, I don't really like the idea of having a website anyway. I'm only pushing it because I think we have to as a php league repo. What's the reality of this @philsturgeon? —Reply to this email directly or view it on GitHub.

[GrahamCampbell]

I'll move this to the v2.1.0 milestone for now then.

[GrahamCampbell]

I've had a play around with https://github.com/justinwalsh/daux.io and it looks pretty easy. I've got our docs working fine in it on my pc. A simple solution would be to use that?

[GrahamCampbell]

Tell me what you think: http://muffin.grahamjcampbell.co.uk/test/.

[scottrobertson]

Hmm, does daux.io require PHP on the server? From what I have read it does. We would need something that generates static HTML to host on Github Pages.

[scottrobertson]

But they do look good :)

[GrahamCampbell]

@scottrobertson It is static html. muffin.grahamjcampbell.co.uk is hosted on github pages.

[GrahamCampbell]

The generated html is here: https://github.com/GrahamCampbell/factory-muffin-api-docs/tree/gh-pages/test.

[GrahamCampbell]

@scottrobertson Shall I publish it to this repo's gh-pages then?

[GrahamCampbell]

@philsturgeon Can we have muffin.thephpleague.com cnamed to this repo's gh-pages?

[scottrobertson]

Ohh really? I read on their docs that it needed a PHP server. Maybe that was old docs or something. And yeah, i think it's an awesome start. Not sure how they feel about not using Sculpin though.

[GrahamCampbell]

I'll wait for @philsturgeon to reply before I do anything.