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

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