Repository navigation
Add JSON Documentation #2352
Description
This issue is for tracking the requirements, issues and solutions in generating JSON for the gcloud-common Angular site.
Known Requirements
- Extracting sphinx code examples and place them in
methods[{examples:[]}]. - Generate table of contents from sphinx toc. (index.rst).
- Class linking should be added. i.e. support :class:
gcloud.datastore._generated.query_pb2.Query, this is partially done through types.json. - Source code links (base on relative repo path. i.e.
/google/cloud/datastore/client.py#L25). - "Getting Started" and "Guide" type pages need to be ported.
- Ensure that snippets are pulled in properly from
docs/*_snippets.py. - Turn on auto
gcloud-common/sitedeployments.
Discussions
- How much data is available in Writers https://groups.google.com/forum/#!topic/sphinx-users/-J1IOOBd-0g
Activity
dhermes commentedon Sep 19, 2016
@daspecster Did you mean to use
gcloud.datastore._generated.query_pb2.Queryas an example? Those generated files don't have any docs.daspecster commentedon Sep 19, 2016
Actually yes I did.
We would need to do one of two things with a reference to generated code.
gcloud/, nowgoogle/cloud).The bigger thing is generating
types.json, I just used that one to illustrate this case.dhermes commentedon Sep 19, 2016
I am 👎 on linking into the source. Those
protocgenerated files are not meant for human eyes and are very nasty to look at.daspecster commentedon Sep 19, 2016
Sorry, I wasn't very clear on that.
Not linking to the source in this case(however that is a required feature for documented modules,classes,methods,params,variables.
I was generating a JSON file for the _generated files as well since I was processing all python files under
gcloudat the time. So the JSON representation was there, but not linked in the TOC. So it just means when there's a reference to one of those in a docstring, the:class:directive works as expected. That is, they could click on the class name and get a description of the module/class/method/whatever.dhermes commentedon Apr 5, 2017
@lukesneeringer is this project still in some long-term "TODO"?
lukesneeringer commentedon Apr 5, 2017
I had no idea this was even a thing.
lukesneeringer commentedon Aug 8, 2017
Denied.
Asset: Add Real Time Feed API Sample Code [(#2352)](GoogleCloudPlatfo…
fix: allow Protobuf 6.x (#2352)
docs: Add code examples to configuration docstrings (#2352)
chore: librarian release pull request: 20260303T181914Z (#2489)