diff --git a/docs/scripts/patch_devsite_toc.py b/docs/scripts/patch_devsite_toc.py index cfe805261..cbd904633 100644 --- a/docs/scripts/patch_devsite_toc.py +++ b/docs/scripts/patch_devsite_toc.py @@ -80,7 +80,9 @@ def __init__(self, dir_name, index_file_name): # load the file to get the title with open(f"{dir_name}/{file_name}.rst", "r") as f2: file_title = f2.readline().replace("\n", "") - self.items.append({"name": file_title, "href": f"{file_name}.md"}) + self.items.append( + {"name": file_title, "href": f"{file_name}.md"} + ) else: # if we are out of the indented block, we are done break @@ -96,7 +98,7 @@ def copy_markdown(self): """ Copy markdown files from _build/markdown/dir_name to _build/html/docfx_yaml - This is necessary because the markdown files in dub-directories + This is necessary because the markdown files in dub-directories are not copied over by the docfx build by default """ for file in os.listdir("_build/markdown/" + self.dir_name): @@ -116,7 +118,11 @@ def validate_toc(toc_file_path, expected_section_list, added_sections): assert section.title in found_sections # make sure each rst file in each custom section dir is listed in the toc for section in added_sections: - items_in_toc = [d["items"] for d in current_toc[0]["items"] if d["name"] == section.title and ".rst"][0] + items_in_toc = [ + d["items"] + for d in current_toc[0]["items"] + if d["name"] == section.title and ".rst" + ][0] items_in_dir = [f for f in os.listdir(section.dir_name) if f.endswith(".rst")] # subtract 1 for index assert len(items_in_toc) == len(items_in_dir) - 1 @@ -126,7 +132,11 @@ def validate_toc(toc_file_path, expected_section_list, added_sections): assert any(d["href"] == f"{base_name}.md" for d in items_in_toc) # make sure the markdown files are present in the docfx_yaml directory for section in added_sections: - items_in_toc = [d["items"] for d in current_toc[0]["items"] if d["name"] == section.title and ".rst"][0] + items_in_toc = [ + d["items"] + for d in current_toc[0]["items"] + if d["name"] == section.title and ".rst" + ][0] md_files = [d["href"] for d in items_in_toc] for file in md_files: assert os.path.exists(f"_build/html/docfx_yaml/{file}") diff --git a/noxfile.py b/noxfile.py index d62dbe000..5867703c8 100644 --- a/noxfile.py +++ b/noxfile.py @@ -427,17 +427,17 @@ def docfx(session): ) # Customization: Add extra sections to the table of contents for the Standard vs Async clients import sys + sys.path.append(os.path.abspath(os.path.join("docs", "scripts"))) from docs.scripts import patch_devsite_toc + toc_path = os.path.join("_build", "html", "docfx_yaml", "toc.yml") custom_sections = [ patch_devsite_toc.TocSection( - dir_name="async_data_client", - index_file_name="async_data_usage.rst" + dir_name="async_data_client", index_file_name="async_data_usage.rst" ), patch_devsite_toc.TocSection( - dir_name="standard_client", - index_file_name="usage.rst" + dir_name="standard_client", index_file_name="usage.rst" ), ] patch_devsite_toc.add_sections(toc_path, custom_sections) @@ -445,10 +445,15 @@ def docfx(session): patch_devsite_toc.validate_toc( toc_file_path=toc_path, expected_section_list=[ - "Overview", "bigtable APIs", "Changelog", "Multiprocessing", - "Async Data Client", "Standard Client", "Bigtable" + "Overview", + "bigtable APIs", + "Changelog", + "Multiprocessing", + "Async Data Client", + "Standard Client", + "Bigtable", ], - added_sections=custom_sections + added_sections=custom_sections, )