Skip to content

Removing unused RST files #32547

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Oct 18, 2023
Merged

Removing unused RST files #32547

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d2699a6
Removing unused RST files
lmazuel Oct 17, 2023
9ee7aa8
Update eng/tox/run_sphinx_apidoc.py
lmazuel Oct 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 17 additions & 7 deletions eng/tox/run_sphinx_apidoc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
from prep_sphinx_env import should_build_docs
import sys
import shutil
from pathlib import Path

from ci_tools.parsing import ParsedSetup

Expand All @@ -31,33 +32,42 @@ def copy_existing_docs(source, target):
logging.info("Copying {}".format(file))
shutil.copy(os.path.join(source, file), target)

def sphinx_apidoc(working_directory):
def sphinx_apidoc(working_directory: str, namespace: str) -> None:
working_doc_folder = os.path.join(args.working_directory, "unzipped", "doc")
command_array = [
"sphinx-apidoc",
"--no-toc",
"--module-first",
"-o",
os.path.join(args.working_directory, "unzipped/docgen"),
os.path.join(args.working_directory, "unzipped/"),
os.path.join(args.working_directory, "unzipped/test*"),
os.path.join(args.working_directory, "unzipped/docgen"), # This is the output folder
os.path.join(args.working_directory, "unzipped/"), # This is the input folder
os.path.join(args.working_directory, "unzipped/test*"), # Starting here this, is excluded
os.path.join(args.working_directory, "unzipped/example*"),
os.path.join(args.working_directory, "unzipped/sample*"),
os.path.join(args.working_directory, "unzipped/setup.py"),
]

try:
# if a `doc` folder exists, just leverage the sphinx sources found therein.
if os.path.exists(working_doc_folder):
if os.path.exists(working_doc_folder):
logging.info("Copying files into sphinx source folder.")
copy_existing_docs(working_doc_folder, os.path.join(args.working_directory, "unzipped/docgen"))

# otherwise, we will run sphinx-apidoc to generate the sources
else:
else:
logging.info("Sphinx api-doc command: {}".format(command_array))
check_call(
command_array
)
# We need to clean "azure.rst", and other RST before the main namespaces, as they are never
# used and will log as a warning later by sphinx-build, which is blocking strict_sphinx
base_path = Path(os.path.join(args.working_directory, "unzipped/docgen/"))
namespace = namespace.rpartition('.')[0]
while namespace:
rst_file_to_delete = base_path / f"{namespace}.rst"
logging.info(f"Removing {rst_file_to_delete}")
rst_file_to_delete.unlink()
namespace = namespace.rpartition('.')[0]
except CalledProcessError as e:
logging.error(
"sphinx-apidoc failed for path {} exited with error {}".format(
Expand Down Expand Up @@ -124,6 +134,6 @@ def mgmt_apidoc(working_directory: str, target_folder: str):
if is_mgmt_package(pkg_details.name):
mgmt_apidoc(output_directory, pkg_details.folder)
else:
sphinx_apidoc(args.working_directory)
sphinx_apidoc(args.working_directory, pkg_details.namespace)
else:
logging.info("Skipping sphinx source generation for {}".format(pkg_details.name))