From daa496c76a15bc15241b5101e5a01a9e39a975b5 Mon Sep 17 00:00:00 2001 From: ZergLev Date: Fri, 27 Sep 2024 15:41:13 +0300 Subject: [PATCH] minor self-review changes --- docs/source/builder.py | 13 ++++++++----- docs/source/poly.py | 15 ++++++++------- scripts/doc.py | 4 ++-- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/source/builder.py b/docs/source/builder.py index 2c38b64a4..bc5fc4ebf 100644 --- a/docs/source/builder.py +++ b/docs/source/builder.py @@ -21,7 +21,7 @@ from sphinx_polyversion.sphinx import CommandBuilder, Placeholder -class DffSphinxBuilder(CommandBuilder): +class ChatskySphinxBuilder(CommandBuilder): def __init__( self, source: str | PurePath, @@ -94,16 +94,19 @@ def replace(v: Any) -> str: clean_docs(str(output_dir)) # doing DFF funcs before doc building - scripts.doc.dff_funcs(str(root_dir)) + scripts.doc.pre_sphinx_build_funcs(str(root_dir)) setup_module.setup(str(root_dir), str(output_dir)) # Using the newest conf.py file instead of the old one - # This feature can be turned on, in case anyone needs it to build old versions with a newer design. Just don't forget to configure poly.py - NEW_SPHINX_CONFIGS = False - if NEW_SPHINX_CONFIGS: + # This feature can be turned on, in case anyone needs it to build old versions with a newer design. + # Just don't forget to configure poly.py + new_sphinx_configs = False + if new_sphinx_configs: newer_conf_path = (os.getcwd() + "/docs/source/conf.py") older_conf_path = str(source_dir) + "/conf.py" shutil.copyfile(newer_conf_path, older_conf_path) + # If you add your own conf.py path there, you could build with any conf.py, + # meaning you could add features like the version-switcher button. # pre hook if self.pre_cmd: diff --git a/docs/source/poly.py b/docs/source/poly.py index ede62034e..25e2ac637 100644 --- a/docs/source/poly.py +++ b/docs/source/poly.py @@ -5,7 +5,7 @@ from sphinx_polyversion.git import * from sphinx_polyversion.git import closest_tag from sphinx_polyversion.pyvenv import Poetry -from docs.source.builder import DffSphinxBuilder +from docs.source.builder import ChatskySphinxBuilder from docs.source.switcher_gen import generate_switcher import git import os @@ -13,8 +13,9 @@ # Generate switcher.json file generate_switcher() -#: Regex matching the branches to build docs for -# This regex stands for all branches except master, so docs can be built for any branch on demand. (if the workflow is launched from it) +# Regex matching the branches to build docs for +# This regex stands for all branches except master, so docs can be built for any branch on demand. +# (if the workflow is launched from it) BRANCH_REGEX = r"((?!master).)*" # BRANCH_REGEX = r".*" @@ -24,15 +25,15 @@ repo = git.Repo('./') branch = repo.active_branch -# This variable is set to True during workflow build. It is 'False' during local builds. +# This variable is set to `False` during workflow build. It is 'True' during local builds. LOCAL_BUILD = os.getenv('LOCAL_BUILD', default="True") if LOCAL_BUILD == "True": -# Local builds only build docs for the current branch and no tags. + # Local builds only build docs for the current branch and no tags. BRANCH_REGEX = str(branch) TAG_REGEX = r"-" elif str(branch) == "master": -# Releases are handled here (pushes into master mean a release, so the latest tag is built) + # Releases are handled here (pushes into master mean a release, so the latest tag is built) tags = sorted(repo.tags, key=lambda t: t.commit.committed_datetime) latest_tag = tags[-1] TAG_REGEX = str(latest_tag) @@ -76,7 +77,7 @@ buffer_size=1 * 10**9, # 1 GB predicate=file_predicate([src]), # exclude refs without source dir ), - builder=DffSphinxBuilder(src, args=SPHINX_ARGS), + builder=ChatskySphinxBuilder(src, args=SPHINX_ARGS), env=Poetry.factory(args=POETRY_ARGS), selector=partial(closest_tag, root), template_dir=root / src / "templates", diff --git a/scripts/doc.py b/scripts/doc.py index 46fb3278c..a782ba187 100644 --- a/scripts/doc.py +++ b/scripts/doc.py @@ -64,8 +64,8 @@ def docs(docker: Optional[DockerClient]): exit(1) -# Functions to be called from DffSphinxBuilder before build -def dff_funcs(root_dir: str): +# Functions to be called from ChatskySphinxBuilder before build +def pre_sphinx_build_funcs(root_dir: str): _build_drawio(root_dir) apiref_dir = root_dir + "/docs/source/apiref" apidoc.main(["-e", "-E", "-f", "-o", apiref_dir, "dff"])