Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add summary_overview template #1946

Merged
merged 13 commits into from
Apr 5, 2024
Merged

Conversation

dandhlee
Copy link
Contributor

@dandhlee dandhlee commented Apr 1, 2024

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: googleapis/sphinx-docfx-yaml#365

Fixes b/263399076.

@dandhlee dandhlee requested a review from parthea April 1, 2024 09:19
@dandhlee dandhlee marked this pull request as ready for review April 1, 2024 10:16
@dandhlee dandhlee requested review from a team and chingor13 as code owners April 1, 2024 10:17
@parthea parthea self-assigned this Apr 2, 2024
Copy link
Contributor

@parthea parthea left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM but we should wait for googleapis/sphinx-docfx-yaml#362 to be released, and potentially publish new client libraries with summary_class.html, summary_method.html, and summary_property.html before adding an overview page which links to these pages.

@parthea parthea assigned dandhlee and unassigned parthea Apr 3, 2024
@parthea parthea marked this pull request as draft April 3, 2024 15:15
@parthea
Copy link
Contributor

parthea commented Apr 3, 2024

I've converted this PR to draft until the tasks in #1946 (review) are completed.

dandhlee and others added 2 commits April 3, 2024 13:55
Co-authored-by: Anthonios Partheniou <partheniou@google.com>
Copy link
Contributor Author

@dandhlee dandhlee left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! Please take a look again.

@dandhlee dandhlee assigned parthea and unassigned dandhlee Apr 3, 2024
@dandhlee dandhlee marked this pull request as ready for review April 3, 2024 17:56
@dandhlee dandhlee requested a review from parthea April 3, 2024 18:08
@parthea
Copy link
Contributor

parthea commented Apr 3, 2024

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 #1946 (comment) .

@parthea parthea marked this pull request as draft April 3, 2024 18:16
@parthea
Copy link
Contributor

parthea commented Apr 3, 2024

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
Copy link
Contributor

parthea commented Apr 4, 2024

@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
Copy link
Contributor Author

dandhlee commented Apr 4, 2024

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

@dandhlee
Copy link
Contributor Author

dandhlee commented Apr 5, 2024

@dandhlee dandhlee requested a review from parthea April 5, 2024 12:02
@parthea parthea marked this pull request as ready for review April 5, 2024 12:25
@parthea parthea assigned dandhlee and unassigned parthea Apr 5, 2024
Copy link
Contributor Author

@dandhlee dandhlee left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! Please take a look again.

@dandhlee dandhlee assigned parthea and unassigned dandhlee Apr 5, 2024
synthtool/gcp/common.py Outdated Show resolved Hide resolved
@parthea parthea assigned dandhlee and unassigned parthea Apr 5, 2024
Co-authored-by: Anthonios Partheniou <partheniou@google.com>
Copy link
Contributor

@parthea parthea left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@dandhlee dandhlee merged commit d7c2271 into master Apr 5, 2024
12 checks passed
@dandhlee dandhlee deleted the add_python_summary_pages branch April 5, 2024 19:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants