chore(docs): improve devsite structure #962
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
product-auto-label
bot
added
the
api: bigtable
|
Here is the summary of changes. You are about to add 96 region tags.
You are about to delete 96 region tags.
This comment is generated by snippet-bot.
|
daniel-sanche
commented
May 15, 2024
docs/standard_client/usage.rst
Outdated
| @@ -1,10 +1,15 @@ | |||
| Using the Sync Client | |||
| ===================== | |||
| Standard Client | |||
There was a problem hiding this comment.
Is "Standard Client" a good name for this?
There was a problem hiding this comment.
Potentially? Not sure what's a good name for it though. Bigtable client might be a more generically encapsulating name, but might be confusing with the API section right below it
There was a problem hiding this comment.
I would call it "classic api"
There was a problem hiding this comment.
Maybe "Classic Client"? There's the complication that we also have to communicate the differences between the admin api vs the data api, so API is a bit overloaded
There was a problem hiding this comment.
Classic client seems good
|
Added a feature to remove sections, and used it to remove the bottom "Bigtable" section. This section was a duplicate of the content we have in the two client folders |
igorbernstein2
approved these changes
May 29, 2024
docs/scripts/patch_devsite_toc.py
Outdated
|
|
||
| def remove_sections(toc_file_path, section_list, output_file_path=None): | ||
| """ | ||
| Add new sections to the autogenerated docfx table of contents file |
There was a problem hiding this comment.
I think the doc is a copy/paste error?
docs/standard_client/usage.rst
Outdated
| @@ -1,10 +1,15 @@ | |||
| Using the Sync Client | |||
| ===================== | |||
| Standard Client | |||
There was a problem hiding this comment.
Classic client seems good
product-auto-label
bot
added
size: s
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changes
Previously, the devsite page for bigtable was messy, combining pages for both clients into a single list:
This change adds a post-processing step to
docfx, to add sections for the two client types to the table of contents, to keep things organizedImplementation Details
The table of contents on devsite is configured through
docs/_build/html/docfx_yaml/toc.yml, which is generated uisngnox -s docfxas part of the release pipeline.This PR adds a new script called
patch_devsite_toc.py, which is added as a post-processing step to the end ofnox -s docfxto add new sections to the auto-generated table of contents.As part of the PR, all pages specific to each client have been moved into subfolders in the
docs/directory. These sub-folders can then be referenced bypatch_devsite_toc.pywhen adding new sections to the table of contentsTo avoid docs issues in the future, I also added a verification step to the new script, to make sure the table of contents remains formatted as expected
Staged page available to reviewers on request