From 557c689b0144fadaa97483264da7305e4dfefd85 Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Mon, 25 Mar 2024 16:25:19 +0530 Subject: [PATCH 01/15] minor changes in init versioneddocs --- sphinx_versioned/__main__.py | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/sphinx_versioned/__main__.py b/sphinx_versioned/__main__.py index 7a77637..55353dc 100755 --- a/sphinx_versioned/__main__.py +++ b/sphinx_versioned/__main__.py @@ -1,4 +1,3 @@ -import re import sys import typer @@ -122,7 +121,7 @@ def main( log.remove() log.add(sys.stderr, format=logger_format, level=loglevel.upper()) - select_branches, exclude_branches = parse_branch_selection(branches) + select_branch, exclude_branch = parse_branch_selection(branches) EventHandlers.RESET_INTERSPHINX_MAPPING = reset_intersphinx_mapping EventHandlers.FLYOUT_FLOATING_BADGE = floating_badge @@ -135,19 +134,19 @@ def main( mp_sphinx_compatibility() return VersionedDocs( - { - "chdir": chdir, - "output_dir": output_dir, - "git_root": git_root, - "local_conf": local_conf, + chdir=chdir, + local_conf=local_conf, + output_dir=output_dir, + git_root=git_root, + config={ "prebuild_branches": prebuild, - "select_branches": select_branches, - "exclude_branches": exclude_branches, + "select_branch": select_branch, + "exclude_branch": exclude_branch, "main_branch": main_branch, "quite": quite, "verbose": verbose, "force_branches": force_branches, - } + }, ) From 188128f47729020d98e9921dd9713731680c7aab Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Mon, 25 Mar 2024 16:26:49 +0530 Subject: [PATCH 02/15] Reading sphinx-config `conf.py` to get keyword args for sphinx-versioned-docs Now, selecting branches will take precedence over excluding branches. --- sphinx_versioned/build.py | 70 ++++++++++++++++++++++----------------- 1 file changed, 40 insertions(+), 30 deletions(-) diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index 450af75..8bda00e 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -3,6 +3,7 @@ import shutil import pathlib from sphinx import application +from sphinx.config import Config from sphinx.errors import SphinxError from sphinx.cmd.build import build_main @@ -29,8 +30,9 @@ class VersionedDocs: def __init__(self, config: dict, debug: bool = False) -> None: self.config = config - self._parse_config(config) - self._handle_paths() + + # Read sphinx-conf.py variables + self.read_conf(config) self._versions_to_pre_build = [] self._versions_to_build = [] @@ -65,39 +67,48 @@ def __init__(self, config: dict, debug: bool = False) -> None: print(f"\n\033[92m Successfully built {', '.join([x.name for x in self._built_version])} \033[0m") return - def _parse_config(self, config: dict) -> bool: - for varname, value in config.items(): - setattr(self, varname, value) - - self._additional_args = () - self._additional_args += ("-Q",) if self.quite else () - self._additional_args += ("-vv",) if self.verbose else () - return True - - def _handle_paths(self) -> None: - """Method to handle cwd and path for local config, as well as, configure - :class:`~sphinx_versioned.versions.GitVersions` and the output directory. - """ - self.chdir = self.chdir if self.chdir else os.getcwd() - log.debug(f"Working directory {self.chdir}") - - self.versions = GitVersions(self.git_root, self.output_dir, self.force_branches) - self.output_dir = pathlib.Path(self.output_dir) - self.local_conf = pathlib.Path(self.local_conf) - + def read_conf(self, config) -> bool: if self.local_conf.name != "conf.py": self.local_conf = self.local_conf / "conf.py" + # If default conf.py location fails if not self.local_conf.exists(): log.error(f"conf.py does not exist at {self.local_conf}") raise FileNotFoundError(f"conf.py not found at {self.local_conf.parent}") log.success(f"located conf.py") + + # Parse sphinx config file i.e. conf.py + self._sphinx_conf = Config.read(self.local_conf.parent.absolute()) + sv_conf_values = { + x.replace("sv_", ""): y for x, y in self._sphinx_conf._raw_config.items() if x.startswith("sv_") + } + log.error(sv_conf_values) + log.critical(config) + + master_config = config.copy() + for x, y in master_config.items(): + if y or x not in sv_conf_values: + continue + master_config[x] = sv_conf_values.get(x) + log.error(master_config) + + for varname, value in master_config.items(): + setattr(self, varname, value) + + # Set additional config for sphinx + self._additional_args = () + self._additional_args += ("-Q",) if self.quite else () + self._additional_args += ("-vv",) if self.verbose else () + + # Initialize GitVersions instance + self.versions = GitVersions(self.git_root, self.output_dir, self.force_branches) return - def _select_branches(self) -> None: - if not self.select_branches: + def _select_branch(self) -> None: + if not self.select_branch: self._versions_to_pre_build = self._all_branches + self._exclude_branch() return for tag in self.select_branches: @@ -112,8 +123,8 @@ def _select_branches(self) -> None: return - def _exclude_branches(self) -> None: - if not self.exclude_branches: + def _exclude_branch(self) -> None: + if not self.exclude_branch: return _names_versions_to_pre_build = [x.name for x in self._versions_to_pre_build] @@ -125,12 +136,11 @@ def _exclude_branches(self) -> None: return def _select_exclude_branches(self) -> list: - log.debug(f"Instructions to select: `{self.select_branches}`") - log.debug(f"Instructions to exclude: `{self.exclude_branches}`") + log.debug(f"Instructions to select: `{self.select_branch}`") + log.debug(f"Instructions to exclude: `{self.exclude_branch}`") self._versions_to_pre_build = [] - self._select_branches() - self._exclude_branches() + self._select_branch() log.info(f"selected branches: `{[x.name for x in self._versions_to_pre_build]}`") return From d6ae7d4d10db7184ee4a7995644a62b43466b33d Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Mon, 25 Mar 2024 16:36:07 +0530 Subject: [PATCH 03/15] added docstring --- sphinx_versioned/build.py | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index 8bda00e..6dc414a 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -25,7 +25,16 @@ class VersionedDocs: Parameters ---------- + chdir : :class:`str` + chdir location + local_conf : :class:`str` + Location for sphinx `conf.py`. + output_dir : :class:`str` + Documentation output directory. + git_root : :class:`str` + If git root differs from chdir/CWD, that location can be supplied via this variable. config : :class:`dict` + CLI configuration arguments. """ def __init__(self, config: dict, debug: bool = False) -> None: @@ -67,7 +76,8 @@ def __init__(self, config: dict, debug: bool = False) -> None: print(f"\n\033[92m Successfully built {', '.join([x.name for x in self._built_version])} \033[0m") return - def read_conf(self, config) -> bool: + def read_conf(self) -> bool: + """Read and parse `conf.py`, CLI arugments to make a master config.""" if self.local_conf.name != "conf.py": self.local_conf = self.local_conf / "conf.py" @@ -83,10 +93,10 @@ def read_conf(self, config) -> bool: sv_conf_values = { x.replace("sv_", ""): y for x, y in self._sphinx_conf._raw_config.items() if x.startswith("sv_") } - log.error(sv_conf_values) - log.critical(config) + log.debug(f"Configuration file arugments: {sv_conf_values}") - master_config = config.copy() + # Make a master config variable + master_config = self.config.copy() for x, y in master_config.items(): if y or x not in sv_conf_values: continue From 547f5f083335b7fafcc8391bd5e640318f07c85c Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Mon, 25 Mar 2024 16:38:18 +0530 Subject: [PATCH 04/15] changelog --- docs/changes/78.breaking.rst | 1 + docs/changes/78.feature.rst | 1 + sphinx_versioned/build.py | 5 ++--- 3 files changed, 4 insertions(+), 3 deletions(-) create mode 100644 docs/changes/78.breaking.rst create mode 100644 docs/changes/78.feature.rst diff --git a/docs/changes/78.breaking.rst b/docs/changes/78.breaking.rst new file mode 100644 index 0000000..0b5000c --- /dev/null +++ b/docs/changes/78.breaking.rst @@ -0,0 +1 @@ +Selecting a branch will take precedence over excluding one. diff --git a/docs/changes/78.feature.rst b/docs/changes/78.feature.rst new file mode 100644 index 0000000..a3c1eec --- /dev/null +++ b/docs/changes/78.feature.rst @@ -0,0 +1 @@ +Added support for configuration file arguments, given in sphinx `conf.py` diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index 6dc414a..ac56cf5 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -41,7 +41,7 @@ def __init__(self, config: dict, debug: bool = False) -> None: self.config = config # Read sphinx-conf.py variables - self.read_conf(config) + self.read_conf() self._versions_to_pre_build = [] self._versions_to_build = [] @@ -77,7 +77,7 @@ def __init__(self, config: dict, debug: bool = False) -> None: return def read_conf(self) -> bool: - """Read and parse `conf.py`, CLI arugments to make a master config.""" + """Read and parse `conf.py`, CLI arugments to make a combined master config.""" if self.local_conf.name != "conf.py": self.local_conf = self.local_conf / "conf.py" @@ -101,7 +101,6 @@ def read_conf(self) -> bool: if y or x not in sv_conf_values: continue master_config[x] = sv_conf_values.get(x) - log.error(master_config) for varname, value in master_config.items(): setattr(self, varname, value) From bf99748ec6ccc5cdd5e2018b5bc2bdbd10b9ade1 Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Tue, 26 Mar 2024 02:37:22 +0530 Subject: [PATCH 05/15] minor changes --- sphinx_versioned/build.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index ac56cf5..a572185 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -96,13 +96,13 @@ def read_conf(self) -> bool: log.debug(f"Configuration file arugments: {sv_conf_values}") # Make a master config variable - master_config = self.config.copy() - for x, y in master_config.items(): + self.config = self._raw_cli_config.copy() + for x, y in self.config.items(): if y or x not in sv_conf_values: continue - master_config[x] = sv_conf_values.get(x) + self.config[x] = sv_conf_values.get(x) - for varname, value in master_config.items(): + for varname, value in self.config.items(): setattr(self, varname, value) # Set additional config for sphinx From 56cdb3c56dad85bf2fc4185985b3efa198f82752 Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Wed, 27 Mar 2024 16:05:09 +0530 Subject: [PATCH 06/15] Using the config dict variable instead of assigning individual config-var using setattr. --- sphinx_versioned/build.py | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index a572185..bd5a759 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -54,11 +54,11 @@ def __init__(self, config: dict, debug: bool = False) -> None: self._select_exclude_branches() # if `--force` is supplied with no `--main-branch`, make the `_active_branch` as the `main_branch` - if not self.main_branch: - if self.force_branches: - self.main_branch = self.versions.active_branch.name + if not self.config.get("main_branch"): + if self.config.get("force_branches"): + self.config["main_branch"] = self.versions.active_branch.name else: - self.main_branch = "main" + self.config["main_branch"] = "main" if debug: return @@ -102,20 +102,17 @@ def read_conf(self) -> bool: continue self.config[x] = sv_conf_values.get(x) - for varname, value in self.config.items(): - setattr(self, varname, value) - # Set additional config for sphinx self._additional_args = () - self._additional_args += ("-Q",) if self.quite else () - self._additional_args += ("-vv",) if self.verbose else () + self._additional_args += ("-Q",) if self.config.get("quite") else () + self._additional_args += ("-vv",) if self.config.get("verbose") else () # Initialize GitVersions instance - self.versions = GitVersions(self.git_root, self.output_dir, self.force_branches) + self.versions = GitVersions(self.git_root, self.output_dir, self.config.get("force_branches")) return def _select_branch(self) -> None: - if not self.select_branch: + if not self.config.get("select_branch"): self._versions_to_pre_build = self._all_branches self._exclude_branch() return @@ -133,7 +130,7 @@ def _select_branch(self) -> None: return def _exclude_branch(self) -> None: - if not self.exclude_branch: + if not self.config.get("exclude_branch"): return _names_versions_to_pre_build = [x.name for x in self._versions_to_pre_build] @@ -145,8 +142,8 @@ def _exclude_branch(self) -> None: return def _select_exclude_branches(self) -> list: - log.debug(f"Instructions to select: `{self.select_branch}`") - log.debug(f"Instructions to exclude: `{self.exclude_branch}`") + log.debug(f"Instructions to select: `{self.config.get('select_branch')}`") + log.debug(f"Instructions to exclude: `{self.config.get('exclude_branch')}`") self._versions_to_pre_build = [] self._select_branch() @@ -158,14 +155,14 @@ def _generate_top_level_index(self) -> None: """Generate a top-level ``index.html`` which redirects to the main-branch version specified via ``main_branch``. """ - if self.main_branch not in [x.name for x in self._built_version]: + if self.config.get("main_branch") not in [x.name for x in self._built_version]: log.critical( - f"main branch `{self.main_branch}` not found!! / not building `{self.main_branch}`; " + f"main branch `{self.config.get('main_branch')}` not found!! / not building `{self.config.get('main_branch')}`; " "top-level `index.html` will not be generated!" ) return - log.success(f"main branch: `{self.main_branch}`; generating top-level `index.html`") + log.success(f"main branch: `{self.config.get('main_branch')}`; generating top-level `index.html`") with open(self.output_dir / "index.html", "w") as findex: findex.write( f""" @@ -173,7 +170,7 @@ def _generate_top_level_index(self) -> None: + {self.config.get("main_branch")}/index.html" /> """ ) @@ -231,7 +228,7 @@ def prebuild(self) -> None: The method carries out the transaction via the internal build method :meth:`~sphinx_versioned.build.VersionedDocs._build`. """ - if not self.prebuild_branches: + if not self.config.get("prebuild_branches"): log.info("No pre-builing...") self._versions_to_build = self._versions_to_pre_build return From aa54d348b7d4669a53db480c034d09a06a71841a Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Wed, 27 Mar 2024 16:17:12 +0530 Subject: [PATCH 07/15] Documentation for config file arguments. --- docs/settings.rst | 43 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/docs/settings.rst b/docs/settings.rst index 0167e9b..9992aa2 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -16,12 +16,51 @@ The ``sphinx-versioned-docs`` reads options from two sources: Configuration File Arguments ============================ -Currently, only the ``sv_project_url`` can be set via the ``conf.py``. More options coming in future releases. - .. option:: sv_project_url: Setting this variable will make sure that the ``Project home`` is listed on the versions selector badge/menu. +.. option:: sv_prebuild + + Pre-build all versions to make sure ``sphinx-build`` has no issues and pass-on the successful builds to ``sphinx-versioned-docs``. Default is `True`. + +.. option:: sv_select_branch + + Select any particular branches/tags to build. + The branch/tag names can be separated by ``,`` or ``|``. + + Selecting a branch will always take precedence over excluding one. + + Example: ``sv_select_branch=["main", "v2.0"]`` + The option above will build ``main``, ``v2.0`` and will skip all others. + +.. option:: sv_exclude_branch + + Exclude any particular branches/tags from building workflow. + The branch/tag names can be separated by ``,`` or ``|``. + + Selecting a branch will always take precedence over excluding one. + + Example: ``sv_exclude_branch=["v1.0"]`` + The option above will exclude ``v1.0`` and will build all others. + +.. option:: sv_main_branch + + Specify the main-branch to which the top-level ``index.html`` redirects to. Default is ``main``. + +.. option:: sv_quite + + Silents the output from `sphinx`. Use `--no-quite` to get complete-output from `sphinx`. Default is `True`. + +.. option:: sv_verbose + + Passed directly to sphinx. Specify more than once for more logging in sphinx. Default is `False`. + +.. option:: sv_force_branches + + Force branch selection. Use this option to build detached head/commits. Default is `False`. + + Command Line Arguments ====================== From a4acde9c4d16519def29c59efc51d9212962a4e8 Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Fri, 5 Apr 2024 16:04:26 +0530 Subject: [PATCH 08/15] refactored variable config into `VersionedDocs.configure_vars` refactored building runtime into `VersionedDocs.run`. --- sphinx_versioned/__main__.py | 28 ++++++--------- sphinx_versioned/build.py | 67 +++++++++++++++++++++++++++--------- 2 files changed, 61 insertions(+), 34 deletions(-) diff --git a/sphinx_versioned/__main__.py b/sphinx_versioned/__main__.py index 55353dc..5aa9d92 100755 --- a/sphinx_versioned/__main__.py +++ b/sphinx_versioned/__main__.py @@ -4,8 +4,7 @@ from loguru import logger as log from sphinx_versioned.build import VersionedDocs -from sphinx_versioned.sphinx_ import EventHandlers -from sphinx_versioned.lib import mp_sphinx_compatibility, parse_branch_selection +from sphinx_versioned.lib import parse_branch_selection app = typer.Typer(add_completion=False) @@ -123,32 +122,27 @@ def main( select_branch, exclude_branch = parse_branch_selection(branches) - EventHandlers.RESET_INTERSPHINX_MAPPING = reset_intersphinx_mapping - EventHandlers.FLYOUT_FLOATING_BADGE = floating_badge - - if reset_intersphinx_mapping: - log.warning("Forcing --no-prebuild") - prebuild = False - - if sphinx_compatibility: - mp_sphinx_compatibility() - - return VersionedDocs( + DocsBuilder = VersionedDocs( chdir=chdir, local_conf=local_conf, output_dir=output_dir, git_root=git_root, config={ - "prebuild_branches": prebuild, - "select_branch": select_branch, + "reset_intersphinx_mapping": reset_intersphinx_mapping, + "sphinx_compatibility": sphinx_compatibility, + "force_branches": force_branches, "exclude_branch": exclude_branch, + "floating_badge": floating_badge, + "select_branch": select_branch, + "prebuild": prebuild, "main_branch": main_branch, - "quite": quite, "verbose": verbose, - "force_branches": force_branches, + "quite": quite, }, ) + return DocsBuilder.run() + if __name__ == "__main__": app() diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index bd5a759..3b7586b 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -10,7 +10,7 @@ from loguru import logger as log from sphinx_versioned.sphinx_ import EventHandlers -from sphinx_versioned.lib import TempDir, ConfigInject +from sphinx_versioned.lib import TempDir, ConfigInject, mp_sphinx_compatibility from sphinx_versioned.versions import GitVersions, BuiltVersions, PseudoBranch @@ -42,6 +42,7 @@ def __init__(self, config: dict, debug: bool = False) -> None: # Read sphinx-conf.py variables self.read_conf() + self.configure_conf() self._versions_to_pre_build = [] self._versions_to_build = [] @@ -102,13 +103,38 @@ def read_conf(self) -> bool: continue self.config[x] = sv_conf_values.get(x) + log.debug(f"master config: {self.config}") + return + + def configure_conf(self) -> None: + # Initialize GitVersions instance + self.versions = GitVersions(self.git_root, self.output_dir, self.config.get("force_branches")) + + if self.config.get("floating_badge"): + EventHandlers.FLYOUT_FLOATING_BADGE = True + + if self.config.get("reset_intersphinx_mapping"): + EventHandlers.RESET_INTERSPHINX_MAPPING = True + log.warning("Forcing --no-prebuild") + self.config["prebuild"] = False + + if self.config.get("sphinx_compatibility"): + mp_sphinx_compatibility() + # Set additional config for sphinx self._additional_args = () self._additional_args += ("-Q",) if self.config.get("quite") else () self._additional_args += ("-vv",) if self.config.get("verbose") else () + return - # Initialize GitVersions instance - self.versions = GitVersions(self.git_root, self.output_dir, self.config.get("force_branches")) + def _select_exclude_branches(self) -> list: + log.debug(f"Instructions to select: `{self.config.get('select_branch')}`") + log.debug(f"Instructions to exclude: `{self.config.get('exclude_branch')}`") + self._versions_to_pre_build = [] + + self._select_branch() + + log.info(f"selected branches: `{[x.name for x in self._versions_to_pre_build]}`") return def _select_branch(self) -> None: @@ -141,16 +167,6 @@ def _exclude_branch(self) -> None: return - def _select_exclude_branches(self) -> list: - log.debug(f"Instructions to select: `{self.config.get('select_branch')}`") - log.debug(f"Instructions to exclude: `{self.config.get('exclude_branch')}`") - self._versions_to_pre_build = [] - - self._select_branch() - - log.info(f"selected branches: `{[x.name for x in self._versions_to_pre_build]}`") - return - def _generate_top_level_index(self) -> None: """Generate a top-level ``index.html`` which redirects to the main-branch version specified via ``main_branch``. @@ -228,7 +244,7 @@ def prebuild(self) -> None: The method carries out the transaction via the internal build method :meth:`~sphinx_versioned.build.VersionedDocs._build`. """ - if not self.config.get("prebuild_branches"): + if not self.config.get("prebuild"): log.info("No pre-builing...") self._versions_to_build = self._versions_to_pre_build return @@ -252,7 +268,7 @@ def prebuild(self) -> None: log.success(f"Prebuilding successful for {', '.join([x.name for x in self._versions_to_build])}") return - def build(self) -> None: + def build(self) -> bool: """Build workflow. Method to build the branch in a temporary directory with the modified @@ -274,11 +290,28 @@ def build(self) -> None: self._build(tag.name) self._built_version.append(tag) except SphinxError: - log.error(f"build failed for {tag}") - exit(-1) + log.error(f"Build failed for {tag}") + return False finally: # restore to active branch self.versions.checkout(self._active_branch) + return True + + def run(self) -> bool: + # Prebuild, but returns if `self.config["prebuild"]` is `False` + self.prebuild() + + # Adds our extension to the sphinx-config + application.Config = ConfigInject + + if self.build(): + # Adds a top-level `index.html` in `output_dir` which redirects to `output_dir`/`main-branch`/index.html + self._generate_top_level_index() + + print(f"\n\033[92m Successfully built {', '.join([x.name for x in self._built_version])} \033[0m") + return + + log.critical(f"Build failed.") return pass From 21699ce83d78810fd94b6fe80af4bbec9b1ebcab Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Fri, 5 Apr 2024 16:08:55 +0530 Subject: [PATCH 09/15] changelog --- docs/changes/78.feature.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/changes/78.feature.rst b/docs/changes/78.feature.rst index a3c1eec..329fe52 100644 --- a/docs/changes/78.feature.rst +++ b/docs/changes/78.feature.rst @@ -1 +1,4 @@ -Added support for configuration file arguments, given in sphinx `conf.py` +Added support for configuration file arguments. These arguments can be defined in `conf.py`. +Arguments can be defined in `conf.py` as long as the argument name is predeced by ``sv_``. +For example: `select_branch` becomes `sv_select_branch`. +Specific info about the arguments is available in documentation under settings topic. From 74cc0c485f4d7ba67fe5d533946ce217975c0276 Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Fri, 5 Apr 2024 16:32:14 +0530 Subject: [PATCH 10/15] Added `--ignore-conf` argument to ignore configuration file arguments for sphinx-versioned-docs in `conf.py`. --- docs/settings.rst | 23 +++++++++++++++++++---- sphinx_versioned/__main__.py | 33 +++++++++++++++++++++------------ sphinx_versioned/build.py | 13 ++++++------- 3 files changed, 46 insertions(+), 23 deletions(-) diff --git a/docs/settings.rst b/docs/settings.rst index 9992aa2..ac814b1 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -20,10 +20,6 @@ Configuration File Arguments Setting this variable will make sure that the ``Project home`` is listed on the versions selector badge/menu. -.. option:: sv_prebuild - - Pre-build all versions to make sure ``sphinx-build`` has no issues and pass-on the successful builds to ``sphinx-versioned-docs``. Default is `True`. - .. option:: sv_select_branch Select any particular branches/tags to build. @@ -60,6 +56,18 @@ Configuration File Arguments Force branch selection. Use this option to build detached head/commits. Default is `False`. +.. option:: sv_floating_badge + + Turns the version selector menu into a floating badge. Default is `False`. + +.. option:: sv_reset_intersphinx + + Resets intersphinx mapping; acts as a patch for issue `#17 `__. Default is `False`. + +.. option:: sv_sphinx_compability + + Adds compatibility for older sphinx versions by monkey patching certain functions. Default is `False`. + Command Line Arguments ====================== @@ -111,6 +119,13 @@ These command line options must be specified when executing the ``sphinx-version Turns the version selector menu into a floating badge. Default is `False`. +.. option:: --ignore-conf + + Ignores conf.py configuration file arguments for sphinx-versioned-docs. + + .. warning:: + conf.py will still be used in sphinx! + .. option:: --quite, --no-quite Silents the output from `sphinx`. Use `--no-quite` to get complete-output from `sphinx`. Default is `True`. diff --git a/sphinx_versioned/__main__.py b/sphinx_versioned/__main__.py index 5aa9d92..0bad0b0 100755 --- a/sphinx_versioned/__main__.py +++ b/sphinx_versioned/__main__.py @@ -59,6 +59,9 @@ def main( floating_badge: bool = typer.Option( False, "--floating-badge", "--badge", help="Turns the version selector menu into a floating badge." ), + ignore_conf: bool = typer.Option( + False, "--ignore-conf", help="Ignores conf.py configuration file arguments for sphinx-versioned-docs. Warning: conf.py will still be used in sphinx!" + ), quite: bool = typer.Option( True, help="Silent `sphinx`. Use `--no-quite` to get build output from `sphinx`." ), @@ -102,6 +105,8 @@ def main( Main branch to which the top-level `index.html` redirects to. [Default = 'main'] floating_badge : :class:`bool` Turns the version selector menu into a floating badge. [Default = `False`] + ignore_conf : :class:`bool` + Ignores conf.py configuration file arguments for sphinx-versioned-docs. Warning: conf.py will still be used in sphinx! quite : :class:`bool` Quite output from `sphinx`. Use `--no-quite` to get output from `sphinx`. [Default = `True`] verbose : :class:`bool` @@ -121,24 +126,28 @@ def main( log.add(sys.stderr, format=logger_format, level=loglevel.upper()) select_branch, exclude_branch = parse_branch_selection(branches) + config = { + "reset_intersphinx_mapping": reset_intersphinx_mapping, + "sphinx_compatibility": sphinx_compatibility, + "force_branches": force_branches, + "exclude_branch": exclude_branch, + "floating_badge": floating_badge, + "select_branch": select_branch, + "prebuild": prebuild, + "main_branch": main_branch, + "verbose": verbose, + "quite": quite, + } + + filtered_config = {x: y for x, y in config.items() if y} DocsBuilder = VersionedDocs( chdir=chdir, local_conf=local_conf, output_dir=output_dir, git_root=git_root, - config={ - "reset_intersphinx_mapping": reset_intersphinx_mapping, - "sphinx_compatibility": sphinx_compatibility, - "force_branches": force_branches, - "exclude_branch": exclude_branch, - "floating_badge": floating_badge, - "select_branch": select_branch, - "prebuild": prebuild, - "main_branch": main_branch, - "verbose": verbose, - "quite": quite, - }, + ignore_conf=ignore_conf, + config=filtered_config ) return DocsBuilder.run() diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index 3b7586b..b851ecb 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -89,6 +89,10 @@ def read_conf(self) -> bool: log.success(f"located conf.py") + if self.ignore_conf: + self.config = self._raw_cli_config + return + # Parse sphinx config file i.e. conf.py self._sphinx_conf = Config.read(self.local_conf.parent.absolute()) sv_conf_values = { @@ -97,12 +101,7 @@ def read_conf(self) -> bool: log.debug(f"Configuration file arugments: {sv_conf_values}") # Make a master config variable - self.config = self._raw_cli_config.copy() - for x, y in self.config.items(): - if y or x not in sv_conf_values: - continue - self.config[x] = sv_conf_values.get(x) - + self.config = sv_conf_values | self._raw_cli_config log.debug(f"master config: {self.config}") return @@ -115,7 +114,7 @@ def configure_conf(self) -> None: if self.config.get("reset_intersphinx_mapping"): EventHandlers.RESET_INTERSPHINX_MAPPING = True - log.warning("Forcing --no-prebuild") + log.warning("forcing --no-prebuild") self.config["prebuild"] = False if self.config.get("sphinx_compatibility"): From 20ec68b3c5e80e7e3c584edf6f08f08b0d6d92f4 Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Sat, 6 Apr 2024 18:58:17 +0530 Subject: [PATCH 11/15] Compatibility for py3.8 --- sphinx_versioned/__main__.py | 16 ++++++++++------ sphinx_versioned/build.py | 4 +++- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/sphinx_versioned/__main__.py b/sphinx_versioned/__main__.py index 0bad0b0..54070d2 100755 --- a/sphinx_versioned/__main__.py +++ b/sphinx_versioned/__main__.py @@ -60,7 +60,9 @@ def main( False, "--floating-badge", "--badge", help="Turns the version selector menu into a floating badge." ), ignore_conf: bool = typer.Option( - False, "--ignore-conf", help="Ignores conf.py configuration file arguments for sphinx-versioned-docs. Warning: conf.py will still be used in sphinx!" + False, + "--ignore-conf", + help="Ignores conf.py configuration file arguments for sphinx-versioned-docs. Warning: conf.py will still be used in sphinx!", ), quite: bool = typer.Option( True, help="Silent `sphinx`. Use `--no-quite` to get build output from `sphinx`." @@ -120,12 +122,14 @@ def main( ------- :class:`sphinx_versioned.build.VersionedDocs` """ - logger_format = "| {level: <8} | - {message}" - + # Logger init log.remove() + logger_format = "| {level: <8} | - {message}" log.add(sys.stderr, format=logger_format, level=loglevel.upper()) + # Parse --branch into either select/exclude variables select_branch, exclude_branch = parse_branch_selection(branches) + config = { "reset_intersphinx_mapping": reset_intersphinx_mapping, "sphinx_compatibility": sphinx_compatibility, @@ -138,18 +142,18 @@ def main( "verbose": verbose, "quite": quite, } - + # Filtered config dict, containing only variables which are `True` filtered_config = {x: y for x, y in config.items() if y} + # VersionedDocs instance DocsBuilder = VersionedDocs( chdir=chdir, local_conf=local_conf, output_dir=output_dir, git_root=git_root, ignore_conf=ignore_conf, - config=filtered_config + config=filtered_config, ) - return DocsBuilder.run() diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index b851ecb..9d7af90 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -33,6 +33,8 @@ class VersionedDocs: Documentation output directory. git_root : :class:`str` If git root differs from chdir/CWD, that location can be supplied via this variable. + ignore_conf : :class:`bool` + Ignores conf.py configuration file arguments for sphinx-versioned-docs. config : :class:`dict` CLI configuration arguments. """ @@ -101,7 +103,7 @@ def read_conf(self) -> bool: log.debug(f"Configuration file arugments: {sv_conf_values}") # Make a master config variable - self.config = sv_conf_values | self._raw_cli_config + self.config = {**sv_conf_values, **self._raw_cli_config} log.debug(f"master config: {self.config}") return From 125e77bc22303938b701cafb8efab6d60a82d31a Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Thu, 2 May 2024 11:07:04 +0530 Subject: [PATCH 12/15] Renamed internal variable for force branch --- sphinx_versioned/__main__.py | 6 +++--- sphinx_versioned/build.py | 4 ++-- sphinx_versioned/versions.py | 8 ++++---- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/sphinx_versioned/__main__.py b/sphinx_versioned/__main__.py index 54070d2..f5cbafa 100755 --- a/sphinx_versioned/__main__.py +++ b/sphinx_versioned/__main__.py @@ -76,7 +76,7 @@ def main( loglevel: str = typer.Option( "info", "-log", "--log", help="Provide logging level. Example --log debug, default=info" ), - force_branches: bool = typer.Option( + force_branch: bool = typer.Option( False, "--force", help="Force branch selection. Use this option to build detached head/commits. [Default: False]", @@ -115,7 +115,7 @@ def main( Passed directly to sphinx. Specify more than once for more logging in sphinx. [Default = `False`] loglevel : :class:`str` Provide logging level. Example `--log` debug, [Default='info'] - force_branches : :class:`str` + force_branch : :class:`str` Force branch selection. Use this option to build detached head/commits. [Default = `False`] Returns @@ -133,7 +133,7 @@ def main( config = { "reset_intersphinx_mapping": reset_intersphinx_mapping, "sphinx_compatibility": sphinx_compatibility, - "force_branches": force_branches, + "force_branch": force_branch, "exclude_branch": exclude_branch, "floating_badge": floating_badge, "select_branch": select_branch, diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index 9d7af90..36bfc64 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -58,7 +58,7 @@ def __init__(self, config: dict, debug: bool = False) -> None: # if `--force` is supplied with no `--main-branch`, make the `_active_branch` as the `main_branch` if not self.config.get("main_branch"): - if self.config.get("force_branches"): + if self.config.get("force_branch"): self.config["main_branch"] = self.versions.active_branch.name else: self.config["main_branch"] = "main" @@ -109,7 +109,7 @@ def read_conf(self) -> bool: def configure_conf(self) -> None: # Initialize GitVersions instance - self.versions = GitVersions(self.git_root, self.output_dir, self.config.get("force_branches")) + self.versions = GitVersions(self.git_root, self.output_dir, self.config.get("force_branch")) if self.config.get("floating_badge"): EventHandlers.FLYOUT_FLOATING_BADGE = True diff --git a/sphinx_versioned/versions.py b/sphinx_versioned/versions.py index 7ac85b2..ef8bcc0 100644 --- a/sphinx_versioned/versions.py +++ b/sphinx_versioned/versions.py @@ -69,15 +69,15 @@ class GitVersions(_BranchTag): Git repository root directory. build_directory : :class:`str` Path of build directory. - force_branches : :class:`bool` + force_branch : :class:`bool` This option allows `GitVersions` to treat the detached commits as normal branches. Use this option to build docs for detached head/commits. """ - def __init__(self, git_root: str, build_directory: str, force_branches: bool) -> None: + def __init__(self, git_root: str, build_directory: str, force_branch: bool) -> None: self.git_root = git_root self.build_directory = pathlib.Path(build_directory) - self.force_branches = force_branches + self.force_branch = force_branch # for detached head self._active_branch = None @@ -116,7 +116,7 @@ def _parse_branches(self) -> bool: # check if if the current git status is detached, if yes, and if `--force` is supplied -> append: if self.repo.head.is_detached: log.warning(f"git head detached {self.repo.head.is_detached}") - if self.force_branches: + if self.force_branch: log.debug("Forcing detached commit into PseudoBranch") self.all_versions.append(PseudoBranch(self.repo.head.object.hexsha)) From ee6c82e9db66a124966f2018cbdc6cd3eb77fff0 Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Thu, 2 May 2024 11:07:15 +0530 Subject: [PATCH 13/15] docs raw --- docs/conf.py | 2 + docs/settings.rst | 152 ++++++++++++++++++++++++++++------------------ 2 files changed, 96 insertions(+), 58 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 19d1ea5..11eb971 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -254,3 +254,5 @@ "sphinx": ("https://www.sphinx-doc.org/", None), "gitpython": ("https://gitpython.readthedocs.io/en/stable/", None), } + +pygments_style = "github-dark" diff --git a/docs/settings.rst b/docs/settings.rst index ac814b1..a23766d 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -10,63 +10,8 @@ Settings The ``sphinx-versioned-docs`` reads options from two sources: - * From the sphinx ``conf.py`` file. * From the provided command-line-arguments. - -Configuration File Arguments -============================ - -.. option:: sv_project_url: - - Setting this variable will make sure that the ``Project home`` is listed on the versions selector badge/menu. - -.. option:: sv_select_branch - - Select any particular branches/tags to build. - The branch/tag names can be separated by ``,`` or ``|``. - - Selecting a branch will always take precedence over excluding one. - - Example: ``sv_select_branch=["main", "v2.0"]`` - The option above will build ``main``, ``v2.0`` and will skip all others. - -.. option:: sv_exclude_branch - - Exclude any particular branches/tags from building workflow. - The branch/tag names can be separated by ``,`` or ``|``. - - Selecting a branch will always take precedence over excluding one. - - Example: ``sv_exclude_branch=["v1.0"]`` - The option above will exclude ``v1.0`` and will build all others. - -.. option:: sv_main_branch - - Specify the main-branch to which the top-level ``index.html`` redirects to. Default is ``main``. - -.. option:: sv_quite - - Silents the output from `sphinx`. Use `--no-quite` to get complete-output from `sphinx`. Default is `True`. - -.. option:: sv_verbose - - Passed directly to sphinx. Specify more than once for more logging in sphinx. Default is `False`. - -.. option:: sv_force_branches - - Force branch selection. Use this option to build detached head/commits. Default is `False`. - -.. option:: sv_floating_badge - - Turns the version selector menu into a floating badge. Default is `False`. - -.. option:: sv_reset_intersphinx - - Resets intersphinx mapping; acts as a patch for issue `#17 `__. Default is `False`. - -.. option:: sv_sphinx_compability - - Adds compatibility for older sphinx versions by monkey patching certain functions. Default is `False`. + * From the sphinx ``conf.py`` file. Command Line Arguments @@ -111,6 +56,10 @@ These command line options must be specified when executing the ``sphinx-version ``sphinx-versioned --branch="main, -v*"`` + .. note:: + + Selecting a branch will always take precedence over excluding one. + .. option:: -m , --main-branch Specify the main-branch to which the top-level ``index.html`` redirects to. Default is ``main``. @@ -121,10 +70,11 @@ These command line options must be specified when executing the ``sphinx-version .. option:: --ignore-conf - Ignores conf.py configuration file arguments for sphinx-versioned-docs. + Ignores ``conf.py`` configuration file arguments for ``sphinx-versioned-docs``. .. warning:: - conf.py will still be used in sphinx! + + ``conf.py`` will still be used in sphinx! .. option:: --quite, --no-quite @@ -146,3 +96,89 @@ These command line options must be specified when executing the ``sphinx-version .. option:: --help Show the help message in command-line. + + +Configuration File Arguments +============================ + +.. warning:: + + Unfortunately, due to limitations of the current implementation, all path variables + like git-path, output path, local ``conf.py`` path cannot be select + via configuration file argument and must be specified in CLI arguments. + +.. option:: sv_project_url: + + Setting this variable will make sure that the ``Project home`` is listed on the versions selector badge/menu. + +.. option:: sv_select_branch + + Select any particular branches/tags to build. + + The branch/tag names can be specified in an array with names separated by ``,`` or ``|``. + + Example: ``sv_select_branch=["main", "v2.0"]`` + + The option above will build ``main``, ``v2.0`` and will skip all others. + + .. note:: + + Selecting a branch will always take precedence over excluding one. + +.. option:: sv_exclude_branch + + Exclude any particular branches/tags from building workflow. + The branch/tag names can be specified in an array with names separated by ``,`` or ``|``. + + Example: ``sv_exclude_branch=["v1.0"]`` + + The option above will exclude ``v1.0`` and will build all others. + +.. option:: sv_main_branch + + Specify the main-branch to which the top-level ``index.html`` redirects to. Default is ``main``. + +.. option:: sv_verbose + + Passed directly to sphinx. Specify more than once for more logging in sphinx. Default is `False`. + +.. option:: sv_force_branch + + Force branch selection. Use this option to build detached head/commits. Default is `False`. + +.. option:: sv_floating_badge + + Turns the version selector menu into a floating badge. Default is `False`. + +.. option:: sv_reset_intersphinx + + Resets intersphinx mapping; acts as a patch for issue `#17 `__. Default is `False`. + +.. option:: sv_sphinx_compability + + Adds compatibility for older sphinx versions by monkey patching certain functions. Default is `False`. + +Template for ``conf.py`` +------------------------ + +.. code:: + + # conf.py + # sphinx arguments + # ... + # ... + + # sphinx-versioned-docs arguments + # This template will have a project url for `sphinx-versioned-docs` + # will exclude `v1.0` branch + # will set `main` as the main branch + # other options can be enabled, if and as requried. + sv_project_url = "https://www.github.com/devanshshukla99/sphinx-versioned-docs" + sv_select_branch = [] + sv_exclude_branch = ["-v1.0"] + sv_main_branch = "main" + sv_verbose = "" + sv_force_branch = False + sv_floating_badge = False + sv_reset_intersphinx = False + sv_sphinx_compability = False From 500c9fc8d201d236780b2c89788caf6a025870ca Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Wed, 24 Jul 2024 16:20:57 +0530 Subject: [PATCH 14/15] support for config file arguments via `conf.py` --- sphinx_versioned/__main__.py | 18 +++++++++--------- sphinx_versioned/build.py | 30 ++++++++++++++++++++++++------ tests/test_branch_selection.py | 16 ++++++++-------- 3 files changed, 41 insertions(+), 23 deletions(-) diff --git a/sphinx_versioned/__main__.py b/sphinx_versioned/__main__.py index f5cbafa..8a63f1e 100755 --- a/sphinx_versioned/__main__.py +++ b/sphinx_versioned/__main__.py @@ -131,16 +131,16 @@ def main( select_branch, exclude_branch = parse_branch_selection(branches) config = { - "reset_intersphinx_mapping": reset_intersphinx_mapping, - "sphinx_compatibility": sphinx_compatibility, + "quite": quite, + "verbose": verbose, + "prebuild": prebuild, + "main_branch": main_branch, "force_branch": force_branch, + "select_branch": select_branch, "exclude_branch": exclude_branch, "floating_badge": floating_badge, - "select_branch": select_branch, - "prebuild": prebuild, - "main_branch": main_branch, - "verbose": verbose, - "quite": quite, + "sphinx_compatibility": sphinx_compatibility, + "reset_intersphinx_mapping": reset_intersphinx_mapping, } # Filtered config dict, containing only variables which are `True` filtered_config = {x: y for x, y in config.items() if y} @@ -148,11 +148,11 @@ def main( # VersionedDocs instance DocsBuilder = VersionedDocs( chdir=chdir, + git_root=git_root, local_conf=local_conf, output_dir=output_dir, - git_root=git_root, - ignore_conf=ignore_conf, config=filtered_config, + ignore_conf=ignore_conf, ) return DocsBuilder.run() diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index 36bfc64..b02a1d4 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -39,8 +39,26 @@ class VersionedDocs: CLI configuration arguments. """ - def __init__(self, config: dict, debug: bool = False) -> None: - self.config = config + def __init__( + self, + chdir: str, + output_dir: str, + git_root: str, + local_conf: str, + config: dict, + ignore_conf: bool = False, + debug: bool = False, + ) -> None: + if chdir: + log.debug(f"chdir: {chdir}") + os.chdir(chdir) + + self.local_conf = pathlib.Path(local_conf) + self.output_dir = pathlib.Path(output_dir) + self.git_root = git_root + + self._raw_cli_config = config + self.ignore_conf = ignore_conf # Read sphinx-conf.py variables self.read_conf() @@ -144,11 +162,11 @@ def _select_branch(self) -> None: self._exclude_branch() return - for tag in self.select_branches: + for tag in self.config.get("select_branch"): filtered_tags = fnmatch.filter(self._lookup_branch.keys(), tag) if filtered_tags: self._versions_to_pre_build.extend([self._lookup_branch.get(x) for x in filtered_tags]) - elif self.force_branches: + elif self.config.get("force_branch"): log.warning(f"Forcing build for branch `{tag}`, be careful, it may or may not exist!") self._versions_to_pre_build.append(PseudoBranch(tag)) else: @@ -161,7 +179,7 @@ def _exclude_branch(self) -> None: return _names_versions_to_pre_build = [x.name for x in self._versions_to_pre_build] - for tag in self.exclude_branches: + for tag in self.config.get("exclude_branch"): filtered_tags = fnmatch.filter(_names_versions_to_pre_build, tag) for x in filtered_tags: self._versions_to_pre_build.remove(self._lookup_branch.get(x)) @@ -264,7 +282,7 @@ def prebuild(self) -> None: log.critical(f"Pre-build failed for {tag}") finally: # restore to active branch - self.versions.checkout(self._active_branch.name) + self.versions.checkout(self._active_branch) log.success(f"Prebuilding successful for {', '.join([x.name for x in self._versions_to_build])}") return diff --git a/tests/test_branch_selection.py b/tests/test_branch_selection.py index f3b970b..7cc8a47 100644 --- a/tests/test_branch_selection.py +++ b/tests/test_branch_selection.py @@ -43,17 +43,17 @@ def test_parse_branch_selection_regex(branches, select, exclude): parsed_select, parsed_exclude = parse_branch_selection(branches) ver = VersionedDocs( - { - "chdir": ".", - "output_dir": OUTPATH, - "git_root": BASEPATH.parent, - "local_conf": "docs/conf.py", - "select_branches": parsed_select, - "exclude_branches": parsed_exclude, - "main_branch": "main", + chdir=".", + output_dir=OUTPATH, + git_root=BASEPATH.parent, + local_conf="docs/conf.py", + config={ "quite": False, "verbose": True, + "main_branch": "main", "force_branches": True, + "select_branch": parsed_select, + "exclude_branch": parsed_exclude, }, debug=True, ) From dd26c543dc0e7212f77bb26919a99da4b5633a5f Mon Sep 17 00:00:00 2001 From: Devansh Shukla Date: Wed, 24 Jul 2024 16:36:52 +0530 Subject: [PATCH 15/15] minor fixes --- docs/conf.py | 2 -- docs/settings.rst | 4 ++-- sphinx_versioned/__main__.py | 2 +- tests/test_branch_selection.py | 2 +- 4 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 11eb971..19d1ea5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -254,5 +254,3 @@ "sphinx": ("https://www.sphinx-doc.org/", None), "gitpython": ("https://gitpython.readthedocs.io/en/stable/", None), } - -pygments_style = "github-dark" diff --git a/docs/settings.rst b/docs/settings.rst index a23766d..64c1f29 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -104,7 +104,7 @@ Configuration File Arguments .. warning:: Unfortunately, due to limitations of the current implementation, all path variables - like git-path, output path, local ``conf.py`` path cannot be select + like git-path, output path, local conf.py path cannot be select via configuration file argument and must be specified in CLI arguments. .. option:: sv_project_url: @@ -115,7 +115,7 @@ Configuration File Arguments Select any particular branches/tags to build. - The branch/tag names can be specified in an array with names separated by ``,`` or ``|``. + The branch/tag names can be separated by ``,`` or ``|`` and supports regex. Example: ``sv_select_branch=["main", "v2.0"]`` diff --git a/sphinx_versioned/__main__.py b/sphinx_versioned/__main__.py index 8a63f1e..e3bb836 100755 --- a/sphinx_versioned/__main__.py +++ b/sphinx_versioned/__main__.py @@ -115,7 +115,7 @@ def main( Passed directly to sphinx. Specify more than once for more logging in sphinx. [Default = `False`] loglevel : :class:`str` Provide logging level. Example `--log` debug, [Default='info'] - force_branch : :class:`str` + force_branch : :class:`bool` Force branch selection. Use this option to build detached head/commits. [Default = `False`] Returns diff --git a/tests/test_branch_selection.py b/tests/test_branch_selection.py index 7cc8a47..0c1f13e 100644 --- a/tests/test_branch_selection.py +++ b/tests/test_branch_selection.py @@ -51,7 +51,7 @@ def test_parse_branch_selection_regex(branches, select, exclude): "quite": False, "verbose": True, "main_branch": "main", - "force_branches": True, + "force_branch": True, "select_branch": parsed_select, "exclude_branch": parsed_exclude, },