minor self-review changes

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:

docs/source/poly.py

@@ -5,16 +5,17 @@
 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
 
 # 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",

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"])