clean up script

docs/scripts/patch_devsite_toc.py

@@ -1,19 +1,55 @@
+# 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.
 """
 
 
 import yaml
 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"))