Closed dandhlee closed 4 months ago
I've converted this PR to draft until the tasks in https://github.com/googleapis/synthtool/pull/1946#pullrequestreview-1977141158 are completed.
This may need to wait until after GCP next as we have a release freeze starting Friday. Releases are needed in order to see live versions of summary_class.html
, summary_method.html
and summary_property.html
as mentioned in https://github.com/googleapis/synthtool/pull/1946#discussion_r1549944377 .
Converting to draft until we have live versions of summary_class.html
, summary_method.html
and summary_property.html
which are dependencies for the overview page.
@dandhlee
Will the pages summary_class.html
, summary_method.html
and summary_property.html
appear automatically? There were several packages released from google-cloud-python
in the last 2 days:
https://github.com/googleapis/google-cloud-python/releases
The latest version of gcp-sphinx-docfx-yaml
was used for these releases
https://github.com/googleapis/google-cloud-python/blob/58dbb33195b5d6ae1ee25ee8e09b1cbdf94c5487/packages/google-cloud-speech/noxfile.py#L329
The sphinx plugin released yesterday, so files from today should appear in c.g.c. automatically.
They've been added: https://cloud.google.com/python/docs/reference/speech/latest/summary_class
Adding
summary_overview.md
page as a default. I've considered generating this with the plugin, but since (1) the generated content is consistent throughout libraries, and (2) the overhead on creating the files and working with the rest of the markdown files were taking up a bit too much engineering time, I've opted to creating this as the base file using templating instead.See design: https://docs.google.com/document/d/1FmAOv9ald2W2Set8jPzN-gwQoE992LCWSu40KBVON28/edit?resourcekey=0-JLhux0549oJustMl46l3zA&tab=t.0#heading=h.spykynl1p438. The design allows individual library maintainers to also add additional content into the overview page as needed, see https://cloud.google.com/python/docs/reference/bigframes/latest/summary_overview as an example.
The comment is added (in
[...]: #
format) to help guide authors in the future if they want to add additional content into the overview pages. Verified that it does not convert comment into any HTML comment, and is fully stripped in the actual content.With this change, we'll be able to redirect folks to the summary_overview page instead of looping back to the same entry page.
Sphinx support for overview pages: https://github.com/googleapis/sphinx-docfx-yaml/pull/365
Fixes b/263399076.