diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 7babc05..645a622 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,3 +1,35 @@ +1.3.2.dev8+gd45a443.d20240722 (2024-07-23) +========================================== + +Deprecations and Removals +------------------------- + +- The theme specific versions selector menu/badge is deprecated in favour of consistent experience + across themes. Now, every theme will have the selector menu either in its sidebar or in its + footer(if the theme supports it). (`#47 `__) +- The CLI option ``--branches`` is removed in favour of ``--branch`` and ``-b``. (`#67 `__) + + +Features +-------- + +- Added a feature to either have the vanilla versions selector menu or have it as a floating badge via + using either ``--floating-badge`` or ``--badge`` option available through command-line. (`#47 `__) +- Modified the ``--branch``/ ``-b`` to accomodate branch selection/exclusion. Now, any branch can be selected + by mentioning it in ``--branch``/``--b`` and any can be excluded by adding a ``-`` infront of the branch/tag + name in the cli argument. + Like ``--branch main,-v1.0,v2.0`` will select ``main``, ``v2.0`` and will exclude ``v1.0``. (`#69 `__) +- Added regex support for selecting and excluding branches and tags. + Now, any branch can be selected by mentioning it in ``--branch``/ ``--b`` and any can be excluded by adding a ``-`` + infront of the branch/tag name in the argument. + + Suppose there are 3 branches and tags: ``main, v1.0, v2.0``. + The argument ``--branch main,-v*`` will select ``main`` and will exclude ``v1.0`` and ``v2.0``. + Similarly, the argument ``--branch -main,v*`` will select ``v1.0`` and ``v2.0`` and will exclude ``main``. + + Note: selecting a branch takes presidence over excluding one. (`#80 `__) + + 1.3.1 (2024-02-28) ================== diff --git a/docs/changes/80.feature.rst b/docs/changes/80.feature.rst new file mode 100644 index 0000000..5a04822 --- /dev/null +++ b/docs/changes/80.feature.rst @@ -0,0 +1,9 @@ +Added regex support for selecting and excluding branches and tags. +Now, any branch can be selected by mentioning it in ``--branch``/ ``--b`` and any can be excluded by adding a ``-`` +infront of the branch/tag name in the argument. + +Suppose there are 3 branches and tags: ``main, v1.0, v2.0``. +The argument ``--branch main,-v*`` will select ``main`` and will exclude ``v1.0`` and ``v2.0``. +Similarly, the argument ``--branch -main,v*`` will select ``v1.0`` and ``v2.0`` and will exclude ``main``. + +Note: selecting a branch takes presidence over excluding one. diff --git a/docs/settings.rst b/docs/settings.rst index 517bc9c..0167e9b 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -57,10 +57,12 @@ These command line options must be specified when executing the ``sphinx-version .. option:: -b , --branch - Build docs and the version selector menu only for certain tags and branches. - The branch names can be separated by ``,`` or ``|``. + Build documentation for selected branches and tags. + The branch/tag names can be separated by ``,`` or ``|`` and supports regex. Example: ``sphinx-versioned --branch="main, v1.0, v2.0"`` + + ``sphinx-versioned --branch="main, -v*"`` .. option:: -m , --main-branch diff --git a/docs/tutorial.rst b/docs/tutorial.rst index a667e14..4f24d72 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -95,6 +95,12 @@ some particular branch(s) and tag(s), they can be specified in the ``--branch`` Either of the two options above will select ``main``, ``v2.0`` and will only build these. + .. code-block:: console + + $ sphinx-versioned --branch "main,v*" + + The above argument will select ``main``, ``v1.0`` and ``v2.0`` and will only build these. + #. **For excluding a branch:** mention the branch/tag name with ``-`` in the CLI argument like: .. code-block:: console @@ -103,7 +109,13 @@ some particular branch(s) and tag(s), they can be specified in the ``--branch`` The above command will build all available branches and tags except ``main``, ``v2.0`` -#. **For selecting and excluding simultaneously:** mention the branch/tag name with ``-`` in the CLI argument like: + .. code-block:: console + + $ sphinx-versioned --branch "-v*" + + The above command will build all available branches and tags except ``v1.0``, ``v2.0`` + +#. **For selecting and excluding simultaneously:** mention the branch/tag name with ``-`` in the CLI argument like (mind you selecting takes presidence over excluding one): .. code-block:: console diff --git a/sphinx_versioned/build.py b/sphinx_versioned/build.py index 1b555d3..450af75 100644 --- a/sphinx_versioned/build.py +++ b/sphinx_versioned/build.py @@ -1,4 +1,5 @@ import os +import fnmatch import shutil import pathlib from sphinx import application @@ -26,7 +27,7 @@ class VersionedDocs: config : :class:`dict` """ - def __init__(self, config: dict) -> None: + def __init__(self, config: dict, debug: bool = False) -> None: self.config = config self._parse_config(config) self._handle_paths() @@ -48,6 +49,9 @@ def __init__(self, config: dict) -> None: else: self.main_branch = "main" + if debug: + return + self.prebuild() # Adds our extension to the sphinx-config @@ -97,8 +101,9 @@ def _select_branches(self) -> None: return for tag in self.select_branches: - if tag in self._lookup_branch.keys(): - self._versions_to_pre_build.append(self._lookup_branch.get(tag)) + 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: log.warning(f"Forcing build for branch `{tag}`, be careful, it may or may not exist!") self._versions_to_pre_build.append(PseudoBranch(tag)) @@ -113,8 +118,9 @@ def _exclude_branches(self) -> None: _names_versions_to_pre_build = [x.name for x in self._versions_to_pre_build] for tag in self.exclude_branches: - if tag in _names_versions_to_pre_build: - self._versions_to_pre_build.remove(self._lookup_branch.get(tag)) + 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)) return diff --git a/sphinx_versioned/lib.py b/sphinx_versioned/lib.py index fd9094c..c9bb4b3 100644 --- a/sphinx_versioned/lib.py +++ b/sphinx_versioned/lib.py @@ -103,7 +103,7 @@ def parse_branch_selection(branches: str) -> tuple: ---------- branches : :class:`str` Input CLI-argument. - + Returns ------- select_branches, exclude_branches : :class:`list`, :class:`list` diff --git a/tests/test_branch_selection.py b/tests/test_branch_selection.py index 1cb6c83..f3b970b 100644 --- a/tests/test_branch_selection.py +++ b/tests/test_branch_selection.py @@ -2,8 +2,10 @@ import pytest import pathlib from bs4 import BeautifulSoup as bs +from sphinx_versioned.build import VersionedDocs from sphinx_versioned.lib import parse_branch_selection + VERSIONS_SUPPOSED = { "v1.0": [ "index.html", @@ -29,6 +31,40 @@ def test_parse_branch_selection(branches, select, exclude): assert parsed_exclude == exclude +@pytest.mark.parametrize( + "branches, select, exclude", + [ + ("main,v*", ["main", "v1.0", "v2.0"], []), + ("-v2.*", ["main", "v1.0"], ["v2.0"]), + ("-v*", ["main"], ["v1.0", "v2.0"]), + ], +) +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", + "quite": False, + "verbose": True, + "force_branches": True, + }, + debug=True, + ) + _names_versions_to_pre_build = [x.name for x in ver._versions_to_pre_build] + for tag in select: + assert tag in _names_versions_to_pre_build + for tag in exclude: + assert tag not in _names_versions_to_pre_build + return + + def test_top_level_index(): assert OUTPATH.exists() assert (OUTPATH / "index.html").is_file()