Repository navigation
Usage docs and other prose in RST files not included in docs #2194
Description
We spent a bunch of time writing this content (https://github.com/GoogleCloudPlatform/gcloud-python/blob/master/docs/resource-manager-api.rst) and it's not visible at all on https://googlecloudplatform.github.io/gcloud-python/#/docs/master/gcloud/resource_manager
Can we bring overviews back?
Activity
daspecster commentedon Aug 25, 2016
I'll see if I can pull it in.
dhermes commentedon Aug 25, 2016
@jgeewax Currently the custom docs build doesn't include any prose in our RST docs. (The Sphinx build still works just fine.)
@daspecster Correct me if I'm wrong.
daspecster commentedon Aug 25, 2016
@dhermes you are correct. We will have to find the proper places to put these docs, assuming that I can parse the RST.
dhermes commentedon Aug 25, 2016
Le sigh. Sphinx works and there is no figuring out how to parse needed
daspecster commentedon Aug 25, 2016
I'm not sure that injecting HTML into the site works very well.
@callmehiphop, do you know where we could put something like this? Can the overview.html be dynamic per module and forced to expand?
callmehiphop commentedon Aug 25, 2016
I think there are two keys that would do what you want to accomplish -
descriptionandoverview.overviewis a complete replacement for the overview.html file. Where asdescriptionis just text/html that will be dumped in right after the Getting started section, but before any of the methods.Edit: example
daspecster commentedon Aug 25, 2016
@callmehiphop I thought there was an issue with just dropping html in there?
If there isn't then I guess we could build the HTML for the resource manager docs, but then strip out or try and replace broken/generated links that sphinx makes, which don't match up to the doc site structure and then drop it in the
descriptionfield?There's only one
:ref:in this RST, but I'm trying to account for other ones as well since it would be nice to add other content in a similar way.daspecster commentedon Aug 29, 2016
I talked to @callmehiphop and it turns out my thoughts on adding the HTML were close, we just have to slash escape the double quotes before inserting it into the JSON fields, but they use an AngularJS ext/lib/tool/something to import and parse HTML from the JSON. I'm going to give it a go.
[-]Resource manager overview isn't included?[/-][+]Usage docs and other prose in RST files not included in docs[/+]daspecster commentedon Sep 16, 2016
Also closed by #2267.
But I will add it to a list of requirements for the new docs.
ci: adds new github workflow focused on documentation in prep to depr…
fix: Improve error handling in blob operations (#2194)
docs: update notebook for JSON subfields support in to_pandas_batches…