PhantomJS Documentation Project, please contribute

[@GotNoSugarBaby]

Hi all,

I'm hoping some of you will be able to help us with an effort to grow the documentation for PhantomJS.

Development is being done in a fork of the PhantomJS gh-pages (I've commented out the Google Analytics and added <meta name="robots" content="noindex,nofollow"/> to my version for now).

• Repo: https://github.com/JamieMason/phantomjs/tree/gh-pages
  
• www: http://jamiemason.github.io/phantomjs/api/
  

The main premise for this is to give each member of the API it's own page so there's more scope to go into detail and add examples etc. It also brings all the docs under the nice design of the main site too rather than the Wiki.

I've generated a skeletal site structure for most of the API so far but there's still a lot to be done. As you can see, even before we add additional content and examples - there is a *lot* of content to be migrated from the Wiki.

Would anyone be willing to help?

Thanks,

Jamie Mason

@GotNoSugarBaby

[Nicolas Perriault]

Le 26 août 2013 à 14:33, @GotNoSugarBaby <siun...@gmail.com> a écrit :

> I'm hoping some of you will be able to help us with an effort to grow the documentation for PhantomJS.

This is *very* cool. Thank you very much for this initiative.

> Would anyone be willing to help?

I'll try to spend some time to fill some examples.

Cheers,

--
Nicolas Perriault
https://nicolas.perriault.net/
+33 660 92 08 67

[@GotNoSugarBaby]

Responses here to an Email I got directly, thank you for this;

1. It looks like a phantomJS fork, not a docs project. Would it be clearer to have it as an independent project?

The hope is to have this merged back into phantomjs.org

2. There is a templating language being used. What is it?
E.g. looking at https://github.com/JamieMason/phantomjs/commit/5c020a6f7b389284e547feae5269c74bff9cee2e

The docs are managed using Jekyll which has excellent integration with GitHub, and uses Liquid templates.

3. It'd be nice if the lists were in a 2 or 3 column table. It is hard to pick out the names otherwise. Even better would be if each property or method was on its own row, with a 5-10 word description next to it. E.g.
page.setContent Set the whole page's HTML, rather than load it.
page.stop Abort a loading attempt.
page.switchToChildFrame Change focus of subsequent commands.
(You notice I have the rule of you are not allowed to use any of the words in the function name to describe it.)

Absolutely, please ignore the poor layout - I've not done anything around this. Right now it's just a case of adding the content and the site structure.

4. In the lists each property, method, etc. is prefixed with the module name. That also makes it harder to read and find the function you are looking for.

Fair point yeah, the page title and nav link labels are shared which is the cause of that - I can update that no problem.

[@GotNoSugarBaby]

As far as I can tell, everything in the API docs fork and the phantomjs.org fork generally should match what's on the current phantomjs.org that I could find.

If anyone can see anything missing, or will help - please let me know.

Thanks a lot.

[James Greene]

Very awesome. :)

Only complaint I'll lodge at this point is that I dislike having to scroll down a sizeable chunk of the page to click into the later module's docs.  Would like to see module-specific subsections such that we could like to each from the main API content (paragraphs describing the different modules).

Sincerely,
    James Greene

--
You received this message because you are subscribed to the Google Groups "phantomjs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to phantomjs+...@googlegroups.com.
Visit this group at http://groups.google.com/group/phantomjs.
For more options, visit https://groups.google.com/groups/opt_out.

[@GotNoSugarBaby]

Thanks James I agree with you on that, I've had a go at fixing it if you check back now http://jamiemason.github.io/phantomjs/api/

[James Greene]

Much nicer, thanks!

More notes as I'm looking around more:

  1. I feel like the "Stream objects" page should really just be linked to from within the "File System module" page.

  2. Similarly, we need to add a "Cookie"/"Cookie objects" page/section within the "Web Page module" page.

  3. I really like how the page for the File System module has a little code snippet showing the `require` statement to "get started" with it. We need to get similar snippets onto the other four module pages, especially since the pages now have "pretty" names (e.g. "Web Page", "File System", etc.) instead of their programmatic names (e.g. "webpage", "fs", etc.).

  4. I noticed there aren't any docs here for the PhantomJS command line config options.  While they are debatably not part of the API, per se, they are still very important.  Would you be OK with adding another page for that to the API docs, or would you propose an alternative location that we can just link to from the main API page?

  5. I'd like to see any references to code within paragraphs styled to look like code. For example, the Child Process page (http://jamiemason.github.io/phantomjs/api/child_process/) mentions `child_process` but it doesn't stand out terribly well as it is in the same font as the rest of the non-code paragraph.  I already fiddled with the markup using Chrome's inspector and I see that we just need to add a <code> element around the relevant bits to make it so (the CSS styling is already correct from "main.css").  So, no major enhancement needed here, just a matter of going through the content and marking appropriate bits up.

This is such an awesome start!  Thanks for initiating this effort, Jamie.

Sincerely,
    James Greene

[James Greene]

Oh, also: I'm not that familiar with Jekyll so could you please briefly explain the prerequisites and build steps?

I'm also a bit confused by the date-stamped filenames as that seems weird for PRs... I'm assuming they get updated during the build when the file's metadata timestamp is changed, right?

Thanks in advance!

Sincerely,
    James Greene

[Ariya Hidayat]

Awesome job! Thanks again Jamie for taking the time to improve our
state of documentation!

I did a cursory look and so far I don't spot anything major. With some
of the minor suggestions noted by James, I think it will be in a state
ready to be landed. Looking forward to seeing and merging that pull
request :)

Can't wait to see more contributions like this in the future!

Best regards,


--
Ariya Hidayat, http://ariya.ofilabs.com
http://twitter.com/ariyahidayat
http://gplus.to/ariyahidayat

[@GotNoSugarBaby]

@James Thanks for all that detail, here are some responses to your points;

1) Stream Objects

Agree, they were made to look like first class members of the API as they were when they're not _really_. I've removed them from the API nav and instead linked to that section from the fs and fs.open pages.

2) Cookie section 

I could use some more help/info on this please. I found it a little odd in the current wiki that Cookies have their own bit in an appendix (https://github.com/ariya/phantomjs/wiki/API-Reference#appendix). I couldn't think of a place to rehome this as how it was didn't seem a natural fit, do you know what I mean? What kind of role would this section play vs what we might describe in the addCookie, deleteCookie etc pages? 

3) 'require' module snippets

I've added this to the other module pages too.

4) I had a page for them copied from the Wiki but I couldn't find anywhere I linked to them. I've moved it to the Docs > Learn section - does this seem ok?

5) child_process to go in a <code> element

The sentence "To start using, you must require a reference to the child_process module"? That's in a code element.

6) Jekyll build steps

I'll add a CONTRIBUTE.md to the gh-pages branch shortly

7) date stamped filenames

It's a required convention of Jekyll which doesn't _really_ apply to our use case - we could put any old date in there really but sadly it's required that file names fit that format. They don't get updated, they just stay as they were when the file was created. I think this idea probably feels more natural if we were creating a blog, but again yeah - our use case has no real place for them.

@Ariya Great, thanks a lot, look forward to seeing that merge when we get there.

[@GotNoSugarBaby]

@James - That CONTRIBUTING.md is now up on gh-pages, I've rattled through it fairly quickly though so please let me know if anything is not clear, thanks again.

On Monday, 26 August 2013 13:33:25 UTC+1, @GotNoSugarBaby wrote:

[Darren Cook]

Minor navigation issue.

API -> Phantom Object --> injectJS

I now have no link to get back to "Phantom Object". (I expected the red
heading would take me there.)


Bigger navigation issue: links don't work.
E.g.
API -> Phantom Object --> addCookie.

The text says "See phantom.cookies for...". When I click
"phantom.cookies it goes nowhere. The link appears to be local:

http://jamiemason.github.io/phantomjs/api/phantom/method/add-cookie.html#phantom-cookies


Is this a copy-and-paste issue and we just have to fix them as we notice
them? Or is it something more systematic you can fix by changing One
Magic Line?

Darren

[@GotNoSugarBaby]

I now have no link to get back to "Phantom Object". (I expected the red  heading would take me there.) 

Good point yeah, I'll add links to the red headers to make that easier.

Is this a copy-and-paste issue and we just have to fix them as we notice them? Or is it something more systematic you can fix by changing One Magic Line? 

It's a copy-and-paste issue yeah, but I should be able to find them a little quicker by searching for href="# in the _site folder to help weed them out.

Thanks a lot Darren,

[@GotNoSugarBaby]

Hey guys,

Everything should be up to date with your feedback now at http://jamiemason.github.io/phantomjs/api/

Please let me know of anything else which is needed, thanks.

Jamie

On Monday, 26 August 2013 13:33:25 UTC+1, @GotNoSugarBaby wrote:

[Ariya Hidayat]

Just an update, I merge this new documentation site, take a look at
e.g. http://phantomjs.org/api/webpage/. Kudos to Jamie for this
awesome work!

Some more remaining work:

* Make sure that any recent changes in the current wiki are transferred there.
* Mark the current wiki docs as deprecated and link to the current doc site.

If Jamie or other Jekyll experts can give me an idea, I'd like to sort
the sidebar (see e.g. http://phantomjs.org/documentation/) based on
some predefined sequence, not alphabetical. This is because the
"Learn" section makes only sense if it starts with Getting Started and
followed by those different use cases etc. IOW it should resemble the
sequence of a step-by-step learning material.

As usual, feedback and help and comment are warmly welcomed!


Thank you!

--
Ariya Hidayat, http://ariya.ofilabs.com
http://twitter.com/ariyahidayat

http://google.com/+AriyaHidayat

[@GotNoSugarBaby]

I can pick that sidebar up, I'll create a new Pull Request soon.

[@GotNoSugarBaby]

Pull request opened: https://github.com/ariya/phantomjs/pull/11792

[Ariya Hidayat]

There is another hug issue: for some reason Google doesn't like it anymore:

https://www.google.com/#q=phantomjs

If someone can take a look at as soon as possible, that'll be appreciated!

Thank you!

> --
> You received this message because you are subscribed to the Google Groups
> "phantomjs" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to phantomjs+...@googlegroups.com.
> Visit this group at http://groups.google.com/group/phantomjs.
> For more options, visit https://groups.google.com/groups/opt_out.

[Jamie Mason]

Hey Ariya, please see your DMs on Twitter. Thanks.

You received this message because you are subscribed to a topic in the Google Groups "phantomjs" group.

To unsubscribe from this topic, visit https://groups.google.com/d/topic/phantomjs/7OziTaTiB3Q/unsubscribe.

To unsubscribe from this group and all its topics, send an email to phantomjs+...@googlegroups.com.

[Ariya Hidayat]

Thanks to Jamie's instant response and help, this is fixed now.
Next time Google crawls the site, it should be alive again. W00t!