Generate docs and host on googlecloudplatform.github.io/gcloud-node ?

[jgeewax]

Some options I've seen:

• Groc (https://github.com/nevir/groc)
• Docco (http://jashkenas.github.io/docco/)
• Dox (https://github.com/visionmedia/dox)

---

I personally really like the docs for Express: http://expressjs.com/3x/api.html

[rakyll]

My personal choice is dox, it works nicely with jsdoc and allows examples to be documented inline. The downside is that it doesn't generate pages, but provides JSON with extracted meta information.

[rakyll]

@aliafshar is working with another person on the gcloud homepage. Once they come up with an initial template, we can generate Dox docs.

[stephenplusplus]

@rakyll can you catch this issue up with any developments? I'm happy to start going through the code and adding examples, as well as spreading the readme out to new .md files.

[silvolu]

@stephenplusplus I have a meeting today at 14 Pacific to discuss about templates etc.
Starting to add examples through the code sounds good to me, unless @rakyll has some other coding tasks in mind for you.

[stephenplusplus]

Hope the meeting went well! I played around with JSDoc today - here's an example of Dataset, the generated Markdown, and its source.

[rakyll]

unless @rakyll has some other coding tasks in mind for you.

SGTM.

[silvolu]

@stephenplusplus could you put the PubSub refactoring on ice for the moment and work on docs for Datastore and Storage? we need to focus on completing M1, and PubSub is not part of it. Thanks!

[stephenplusplus]

I would be happy to! I believe I linked to an example of a js doc overhaul
of Datastore.dataset earlier in this thread. Any thoughts on that before I
move on to other sections?

Something worth noticing, which I'm sure I don't need to point out, is the
cumbersome dominance of the doc blocks once you add examples in. I foresee
maintenance of the blocks being an area of trouble, as it's not always
obvious which examples include a piece of an API that you're refactoring.

As an example, if I change the Query object and update the examples in its
query.js file, I might not know to look for the example of using a Query
object which was shown as part of the Dataset.runQuery documentation in
dataset.js. We can try to isolate examples to prevent this, but it ends up
hurting the quality of the examples, as no example would be a complete
"start to finish" example.

Hope that made sense. The only alternative I can think of to address the
problem would be simply splitting the current readme up into different
sections, then putting complete usage examples there.

Just things to keep in mind!

On Wednesday, August 13, 2014, Silvano Luciani [email protected]
wrote:

@stephenplusplus https://github.com/stephenplusplus could you put the
PubSub refactoring on ice for the moment and work on docs for Datastore and
Storage? we need to focus on completing M1, and PubSub is not part of it.
Thanks!

—
Reply to this email directly or view it on GitHub
#19 (comment)
.

[silvolu]

The PoC looks good to me, and in the end, as long as we're adding jsdoc, it will be easy to switch to Dox or similar.

Regarding the maintenance problem, I think themaintaining samples not directly related to an API change would also apply to several .md files containing the docs. At least in this way we make sure that we can update the example directly related to a change, because it will sit in the file that we're changing :). Makes sense?

[stephenplusplus]

Sure. Just to clarify the splitting of files, I meant to suggest one
"Datastore" md doc, one "PubSub" etc, so your find and replace would be
limited to one file. Maintenance-made-easy probably is not a realistic
endeavor, so either option will bring us as close as we can get :)

On Wednesday, August 13, 2014, Silvano Luciani [email protected]
wrote:

The PoC looks good to me, and in the end, as long as we're adding jsdoc,
it will be easy to switch to Dox or similar.

Regarding the maintenance problem, I think themaintaining samples not
directly related to an API change would also apply to several .md files
containing the docs. At least in this way we make sure that we can update
the example directly related to a change, because it will sit in the file
that we're changing :). Makes sense?

—
Reply to this email directly or view it on GitHub
#19 (comment)
.

[stephenplusplus]

Closing this since we have this launched. I'm sure we'll have tweaks as we go, but since we're live, I think we can take them on one by one. Feel free to re-open if you feel there's more to discuss.

[silvolu]

Sorry for being a pedant, but we're still waiting for the correct templates, I'll consider this launched when those are in place :)