Find a way to share the HTML + CSS for our gcloud-* docs ?

@dhermes

@jgeewax I think we should tried to have shared HTML / JS / CSS for our custom theme.

It seems the Node.js theme continues to improve while ours looks like an old snapshot of what they had.

Comparing our custom docs to RTD is not great (i.e. ours look not so great):
http://googlecloudplatform.github.io/gcloud-python/latest/gcloud-auth.html
http://gcloud-python.readthedocs.org/en/latest/gcloud-auth.html

UPDATE: I think we should consider just using readthedocs and maybe customizing their theme.

Sharing themes:

I think if we can find a way to generate a JSON output of our docs like the dox script does, we could use the exact same theme. I would really really like that.

/cc @stephenplusplus @callmehiphop to comment

Just using read-the-docs:

I totally get that this is "the Python way to host docs" -- I'm all for it in addition to the gcloud themed docs, the same way I'm all for Javadocs for gcloud-java and Godocs for gcloud-golang (and MSDN looking docs for gcloud-dotnet when we do it). The branding piece is important as well, and I'm fine with us investing the time to continue maintaining these.

Am I correct in the assumption that RTD / Javadocs / etc should take relatively small amounts of work going forward?

@mpmcdonald

/cc @mpmcdonald

Maybe we can export stuff via http://sphinx-doc.org/builders.html#sphinx.builders.html.JSONHTMLBuilder ?

I'm open to it but don't want to write our own custom docs builder. I think the readthedocs.org build script creates the JSON for something (not sure what it's used for).

I think you have to define "docs builder". My suggestion is:

Get Sphinx to spit out some JSON
Massage that JSON into some common format (we'll need to work with the gcloud-node team on this)
Factor out the gcloud-node template (maybe move it over to gcloud-common)
Shove that JSON into the template

I was just making a general statement that we shouldn't put too much work in, since the payoff wouldn't be that large (and since we already have docs).

I think I hear what you're saying -- I'm trying to say "the branded site matters a lot", so unless we're talking about a 6-month, 2-person full-time project... I think we should definitely explore.

I think the effort to move gcloud-nodes site to gcloud-common would be pretty minimal, imo the biggest part would be coming up with a common format for the JSON.

That would be awesome! 👍

UPDATE: From the latest build, it looks like readthedocs.org builds JSON via

sphinx-build -T -b json -d _build/doctrees-json -D language=en . _build/json

@stephenplusplus

I gave that a try, looks like it spits out some HTML formatted stuff, not a structured representation of the parse tree.

Adding a custom builder/writer seems to spit out something more useful: https://gist.github.com/jgeewax/c254f8b4d9f48162eaad

Now we just need to massage it to either look like the gcloud-node JSON (https://github.com/GoogleCloudPlatform/gcloud-node/blob/gh-pages/json/master/datastore/query.json) or massage them both into a common shared format....

@stephenplusplus , thoughts?

Not sure if this will make anyone happy but sphinx has JS support:
http://ericholscher.com/blog/2014/feb/11/sphinx-isnt-just-for-python/
http://sphinx-doc.org/domains.html#the-javascript-domain

e.g. http://bootstrap-datepicker.readthedocs.org/en/latest/

I think finding a common format would be nice. As it is now, the JSON we get has a lot of extra junk in it we don't need. We'll just need to decide what those items are, then post-process our JSON build process.

Method name
Private?
Description
Example
Parameters
- Name
- Type
  - Is a custom type?
- Optional?
- Can be null?
Line of code (this could be optional)

The node docs site is very closely linked to our library's directory structure, which is also our class hierarchy...

Module -> Sub-module
(ex: Storage -> File, Datastore -> Query)

The site's routing is hooked to this tree, as that's also how the JSON is stored: https://github.com/GoogleCloudPlatform/gcloud-node/tree/gh-pages/json/v0.10.0

I'm not sure it's possible to have all languages spit out files by the same structure (docs/json/module/submodule.json) -- if it is, that's a relief. If not, we'll have to figure that out.

One extra thing to note is that in Python for example, we have docs that don't correspond directly to a module (ie, https://googlecloudplatform.github.io/gcloud-python/stable/pubsub-usage.html). Do we have anything comparable on gcloud-node?

I don't think there's a huge issue with the module -> submodule/class structure. We already cram this in a bit with Python based on the left-nav, ie:

Datastore
- Client
- Entities
- Keys
- Queries
- Transactions
- Batches

@blowmage

/cc @blowmage @quartzmo -- can you guys chime in about Ruby at all ?

@quartzmo

@quartzmo my pleasure!

{
  "dns.zone.Zone.createChange": {
    "name": "createChange",
    "description": "<p>Create a change of resource record sets for the zone.</p>",
    "line": 149,
    "type": "method",
    "params": [{
      "name": "options",
      "types": ["object"],
      "description": "<ul>\n<li>The configuration object.</li>\n</ul>\n",
      "optional": false,
      "nullable": false
    }, {
      "name": "options.add",
      "types": ["module:dns/record", "Array.<module:dns/record>"],
      "description": "<ul>\n<li>Record objects     to add to this zone.</li>\n</ul>\n",
      "optional": false,
      "nullable": false
    }, {
      "name": "options.delete",
      "types": ["module:dns/record", "Array.<module:dns/record>"],
      "description": "<ul>\n<li>Record     objects to delete from this zone. Be aware that the resource records here<br />  must match exactly to be deleted.</li>\n</ul>\n",
      "optional": false,
      "nullable": false
    }, {
      "name": "callback",
      "types": ["function"],
      "description": "<ul>\n<li>The callback function.</li>\n</ul>\n",
      "optional": false,
      "nullable": false
    }, {
      "name": "callback.err",
      "types": ["error"],
      "description": "<ul>\n<li>An API error.</li>\n</ul>\n",
      "optional": false,
      "nullable": true
    }, {
      "name": "callback.change",
      "types": ["module:dns/change"],
      "description": "<ul>\n<li>A {module:dns/change} object.</li>\n</ul>\n",
      "optional": false,
      "nullable": true
    }, {
      "name": "callback.apiResponse",
      "types": ["object"],
      "description": "<ul>\n<li>Raw API response. </li>\n</ul>\n",
      "optional": false,
      "nullable": false
    }],
    "example": "var oldARecord = zone.record('a', {\n  name: 'example.com.',\n  data: '1.2.3.4',\n  ttl: 86400\n});\n\nvar newARecord = zone.record('a', {\n  name: 'example.com.',\n  data: '5.6.7.8',\n  ttl: 86400\n});\n\nzone.createChange({\n  add: newARecord,\n  delete: oldARecord\n}, function(err, change, apiResponse) {\n  if (!err) {\n    // The change was created successfully.\n  }\n});"
  }
}

It's probably worth noting that the syntax for the custom types isn't really set in stone, it's just how we had it previously.

Anyone following along here, we've shifted the discussion over to gcloud-common: https://github.com/GoogleCloudPlatform/gcloud-common/issues/33 -- we're finalizing the schema, so please weigh in if you have any objections or just subscribe to stay updated.

Thanks for ~~doing this~~ remembering people watching this thread

Closing this since the discussion moved

Auto-update dependencies. [(#1094)](GoogleCloudPlatform/python-docs-s…

chore: move samples from python-docs-sample (#66)

Auto-update dependencies. [(#1094)](GoogleCloudPlatform/python-docs-s…

move monitoring samples from python-docs-samples (#51)

docs: add samples from bigtable (#38)

feat: add support for long-running operations with rest transport. (#…

chore: release 0.58.0 (#1097)

fix: Use except distinct and intersect distinct (#1094)

chore: update system creds (#1094)

Navigation Menu

Repository navigation

Find a way to share the HTML + CSS for our gcloud-* docs ? #1094

Sharing themes:

Just using read-the-docs:

19 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Find a way to share the HTML + CSS for our gcloud-* docs ? #1094

Description

Sharing themes:

Just using read-the-docs:

Activity

jgeewax commented on Aug 26, 2015

jgeewax commented on Aug 26, 2015

dhermes commented on Aug 26, 2015

jgeewax commented on Aug 26, 2015

dhermes commented on Aug 26, 2015

jgeewax commented on Aug 26, 2015

callmehiphop commented on Aug 26, 2015

dhermes commented on Aug 26, 2015

jgeewax commented on Aug 27, 2015

dhermes commented on Aug 27, 2015

stephenplusplus commented on Aug 27, 2015

jgeewax commented on Aug 27, 2015

jgeewax commented on Aug 27, 2015

jgeewax commented on Aug 27, 2015

19 remaining items

callmehiphop commented on Sep 9, 2015

stephenplusplus commented on Nov 19, 2015

dhermes commented on Nov 19, 2015

dhermes commented on Dec 31, 2015

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions