Usage docs and other prose in RST files not included in docs

[jgeewax]

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?

[daspecster]

I'll see if I can pull it in.

[dhermes]

@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]

@dhermes you are correct. We will have to find the proper places to put these docs, assuming that I can parse the RST.

[dhermes]

Le sigh. Sphinx works and there is no figuring out how to parse needed

[daspecster]

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]

I think there are two keys that would do what you want to accomplish - description and overview.

overview is a complete replacement for the overview.html file. Where as description is just text/html that will be dumped in right after the Getting started section, but before any of the methods.

Edit: example

[daspecster]

@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 description field?

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]

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.

[daspecster]

Also closed by #2267.
But I will add it to a list of requirements for the new docs.