diff --git a/docs/scripts/patch_devsite_toc.py b/docs/scripts/patch_devsite_toc.py index cfd700b73..cfe805261 100644 --- a/docs/scripts/patch_devsite_toc.py +++ b/docs/scripts/patch_devsite_toc.py @@ -1,9 +1,22 @@ +# Copyright 2024 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. """ python-bigtable is made up of multiple clients, which we want to categorize separately in the devsite table of contents. -To accomplish this, we will read in the generated toc file, remove the markdown content, -and replace it with a hand-written template +This script allows us to add separate sections to the autogenerated toc.yml file to +accomplish this. """ @@ -11,9 +24,32 @@ import os import shutil -# set workinf directory to /docs +# set working directory to /docs os.chdir(f"{os.path.dirname(os.path.abspath(__file__))}/{os.pardir}") + +def add_sections(toc_file_path, section_list, output_file_path=None): + """ + Add new sections to the autogenerated docfx table of contents file + + Takes in a list of TocSection objects, which should point to a directory of rst files + within the main /docs directory, which represents a self-contained section of content + + :param toc_file_path: path to the autogenerated toc file + :param section_list: list of TocSection objects to add + :param output_file_path: path to save the updated toc file. If None, save to the input file + """ + current_toc = yaml.safe_load(open(toc_file_path, "r")) + for section in section_list: + current_toc[0]["items"].insert(-1, section.to_dict()) + section.copy_markdown() + # save file + if output_file_path is None: + output_file_path = toc_file_path + with open(output_file_path, "w") as f: + yaml.dump(current_toc, f) + + class TocSection: def __init__(self, dir_name, index_file_name): """ @@ -69,27 +105,6 @@ def copy_markdown(self): f"_build/html/docfx_yaml", ) -def add_sections(toc_file_path, section_list, output_file_path=None): - """ - Add new sections to the autogenerated docfx table of contents file - - Takes in a list of TocSection objects, which should point to a directory of rst files - within the main /docs directory, which represents a self-contained section of content - - :param toc_file_path: path to the autogenerated toc file - :param section_list: list of TocSection objects to add - :param output_file_path: path to save the updated toc file. If None, save to the input file - """ - current_toc = yaml.safe_load(open(toc_file_path, "r")) - for section in section_list: - current_toc[0]["items"].insert(-1, section.to_dict()) - section.copy_markdown() - # save file - if output_file_path is None: - output_file_path = toc_file_path - with open(output_file_path, "w") as f: - yaml.dump(current_toc, f) - def validate_toc(toc_file_path, expected_section_list, added_sections): current_toc = yaml.safe_load(open(toc_file_path, "r"))