Added regex support for selecting and excluding branches and tags (#80)

* added regex support for  selecting and excluding branches and tags

* added changelog

* added tests for regex branch selection

* documentation

* changelog

Author: devanshshukla99

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 <https://github.com/devanshshukla99/sphinx-versioned-docs/pull/47>`__)
+- The CLI option ``--branches`` is removed in favour of ``--branch`` and ``-b``. (`#67 <https://github.com/devanshshukla99/sphinx-versioned-docs/pull/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 <https://github.com/devanshshukla99/sphinx-versioned-docs/pull/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 <https://github.com/devanshshukla99/sphinx-versioned-docs/pull/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 <https://github.com/devanshshukla99/sphinx-versioned-docs/pull/80>`__)
+
+
 1.3.1 (2024-02-28)
 ==================
 

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.

docs/settings.rst

@@ -57,10 +57,12 @@ These command line options must be specified when executing the ``sphinx-version
 
 .. option:: -b <branch names>, --branch <branch names>
 
-    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 <branch name>, --main-branch <branch name>
 

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
 

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
 

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`

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()