googleapis / synthtool

Apache License 2.0
87 stars 82 forks source link

docs: add summary_overview template #1946

Closed dandhlee closed 4 months ago

dandhlee commented 4 months ago

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.

parthea commented 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.

parthea commented 4 months ago

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 .

parthea commented 4 months ago

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.

parthea commented 4 months ago

@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

dandhlee commented 4 months ago

The sphinx plugin released yesterday, so files from today should appear in c.g.c. automatically.

dandhlee commented 4 months ago

They've been added: https://cloud.google.com/python/docs/reference/speech/latest/summary_class