Select/exclude a branch from processing (#69)

* Read and parse CLI ``--branches`` option * Process the selected and excluded branches. * Refactor: Moved the function responsible for getting all versions to `GitVersions` * testing infra for branch selection * simplify branch selection for maintainability * moved branch selection infra to `sphinx_versioned.lib`. * Modified gh-action to accomodate branch selection/exclusion. * updated docstrings * updated documentation * changelog
devanshshukla99 · Mar 19, 2024 · 24bd344 · 24bd344
1 parent 9afa5d7
commit 24bd344
Show file tree

Hide file tree

Showing 11 changed files with 323 additions and 133 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -5,7 +5,6 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
-  workflow_dispatch:
 
 jobs:
   legacy-build:
@@ -15,7 +14,7 @@ jobs:
         python-version: ["3.9"]
     steps:
       - name: Check out repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Check out that no sensitive environment variable is shared
         run: env
       - name: Set up Python ${{ matrix.python-version }}
@@ -46,7 +45,7 @@ jobs:
             toxenv: py310
     steps:
       - name: Check out repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Check out that no sensitive environment variable is shared
         run: env
       - name: Set up Python ${{ matrix.python-version }}
@@ -68,7 +67,7 @@ jobs:
         python-version: ["3.10"]
     steps:
       - name: Check out repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Check out that no sensitive environment variable is shared
         run: env
       - name: Set up Python ${{ matrix.python-version }}
@@ -97,7 +96,7 @@ jobs:
             toxenv: py310
     steps:
       - name: Check out repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Check out that no sensitive environment variable is shared
         run: env
       - name: Set up Python ${{ matrix.python-version }}
@@ -112,7 +111,7 @@ jobs:
         run: |
           tox -e ${{ matrix.toxenv }}
 
-  theme-build:
+  theme-feat-build:
     runs-on: ${{ matrix.os }}
     needs: py-build
     strategy:
@@ -127,9 +126,12 @@ jobs:
           - os: ubuntu-latest
             python-version: "3.10"
             toxenv: alabaster
+          - os: ubuntu-latest
+            python-version: "3.10"
+            toxenv: branch_selection
     steps:
       - name: Check out repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Check out that no sensitive environment variable is shared
         run: env
       - name: Set up Python ${{ matrix.python-version }}

diff --git a/docs/changes/69.feature.rst b/docs/changes/69.feature.rst
@@ -0,0 +1,4 @@
+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``.
diff --git a/docs/install.rst b/docs/install.rst
@@ -4,84 +4,80 @@
 Installation
 ============
 
-The ``sphinx-versioned-docs`` project has the following requirements.
+    The ``sphinx-versioned-docs`` project has the following requirements.
 
 .. _requirements-to-use:
 
 Requirements
-============
-
-.. code-block:: markdown
+------------
 
-    GitPython>=3.1.31
-    loguru>=0.7.0
-    setuptools>=66.0.0
-    sphinx>=4.6.0
-    typer>=0.9.0
-    rich
+    .. code-block:: markdown
 
-Installing
-==========
+        GitPython>=3.1.31
+        loguru>=0.7.0
+        setuptools>=66.0.0
+        sphinx>=4.6.0
+        typer>=0.9.0
 
-Now, it can be installed via the following methods:
+    Now, it can be installed via the following methods:
 
-Installing using pip
---------------------
+1. Installing using pip
+------------------------
 
-For this you will require that python3 and `pip <https://pip.pypa.io/en/stable/installation/>`__ are already installed.
+    For this you will require that python3 and `pip <https://pip.pypa.io/en/stable/installation/>`__ are already installed.
 
-.. code-block:: console
+    .. code-block:: console
 
-    $ pip install sphinx-versioned-docs
+        $ pip install sphinx-versioned-docs
 
-Installing using conda
-----------------------
+2. Installing using conda
+--------------------------
 
-In this method, please make sure that anaconda/conda is properly installed:
+    In this method, please make sure that anaconda/conda is properly installed:
 
-.. code-block:: console
+    .. code-block:: console
 
-    $ conda install sphinx-versioned-docs
+        $ conda install sphinx-versioned-docs
 
-In order to create a separate environment in conda, follow these instructions:
+    In order to create a separate environment in conda, follow these instructions:
 
-.. code-block:: console
+    .. code-block:: console
 
-    $ conda create --name versioned
-    $ conda activate versioned
-    $ conda install sphinx-versioned-docs
+        $ conda create --name versioned
+        $ conda activate versioned
+        $ conda install sphinx-versioned-docs
 
-Installing from source
-----------------------
+3. Installing from source
+--------------------------
 
-This method typically installs that lastest developer version of the package, however, it be used to install stable branches too.
+    This method typically installs that lastest developer version of the package, however, it be used to install stable branches too.
 
-To install the latest developer version:
+    To install the latest developer version:
 
-.. code-block:: console
+    .. code-block:: console
 
-    $ git clone https://github.com/devanshshukla99/sphinx-versioned-docs
-    $ cd sphinx-versioned-docs
-    $ pip install .
+        $ git clone https://github.com/devanshshukla99/sphinx-versioned-docs
+        $ cd sphinx-versioned-docs
+        $ pip install .
 
-To install the latest stable release, specified via the ``<release tag>``:
+    To install the latest stable release, specified via the ``<release tag>``:
 
-.. code-block:: console
+    .. code-block:: console
 
-    $ git clone https://github.com/devanshshukla99/sphinx-versioned-docs
-    $ cd sphinx-versioned-docs
-    $ git checkout <release tag>
-    $ pip install .
+        $ git clone https://github.com/devanshshukla99/sphinx-versioned-docs
+        $ cd sphinx-versioned-docs
+        $ git checkout <release tag>
+        $ pip install .
 
 .. _dev-version:
 
-Installing the developer version
---------------------------------
+4. Installing the developer version
+-------------------------------------
 
-If you are interested in contributing to the project, then you can setup the developer environment by using:
+    If you are interested in contributing to the project, then you can setup the developer environment by using:
 
-.. code-block:: console
+    .. code-block:: console
 
-    $ git clone https://github.com/devanshshukla99/sphinx-versioned-docs
-    $ cd sphinx-versioned-docs
-    $ pip install -e .[all]
+        $ git clone https://github.com/devanshshukla99/sphinx-versioned-docs
+        $ cd sphinx-versioned-docs
+        $ pip install -e .[all]
diff --git a/docs/settings.rst b/docs/settings.rst
@@ -4,9 +4,9 @@
 Settings
 ========
 
-.. code-block::
+.. code-block:: console
 
-    sphinx-versioned [OPTIONS]
+    $ sphinx-versioned [OPTIONS]
 
 The ``sphinx-versioned-docs`` reads options from two sources:
 

diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -12,6 +12,33 @@ Make sure that you've already :ref:`installed <install>` it.
 Building versioned docs
 =======================
 
+.. _initializing_sphinx:
+
+Initializing project with sphinx and git
+----------------------------------------
+
+If you have problems initializing sphinx and git, then follow these instructions, otherwise you can skip directly to :ref:`initializing sphinx-versioned-docs <initializing_versioned_docs>` 
+
+Before we begin make sure you have `sphinx <https://pypi.org/project/Sphinx/>`__ install and some git history already in your project.
+If not, read `first steps with sphinx <http://www.sphinx-doc.org/en/stable/tutorial.html>`_ first.
+If you just want something quick and dirty you can do the following:
+
+.. code-block:: console
+
+    $ sphinx-quickstart docs -p projectname -a author -v version --makefile --no-sep -r version -l en -q
+    $ git checkout -b feature_branch main  # Create new branch from main.
+
+    $ echo -e "Test\n====\n\nSample Documentation" > docs/index.rst  # Create one doc.
+    $ git add .
+    $ git commit -m "initial"
+
+    $ sphinx-versioned
+
+.. _initializing_versioned_docs:
+
+Initializing sphinx-versioned-docs
+----------------------------------
+
 Before using the ``sphinx-versioned-docs`` to build a versioned documentation. Make sure you have following things done:
 
 - [x] Project initialized.
@@ -33,49 +60,60 @@ you can run the following command to generate the versioned documentation:
 
     $ sphinx-versioned
 
------------------
+If you have problems initializing project and running sphinx, then follow at :ref:`initializing sphinx and git <initializing_sphinx>`.
 
-If you have problems initializing sphinx and git, then follow these instructions: 
+------------------------------
 
-Before we begin make sure you have some Sphinx docs already in your project. If not, read `First Steps with Sphinx <http://www.sphinx-doc.org/en/stable/tutorial.html>`_ first. If you just want something quick
-and dirty you can do the following:
+Generated output
+----------------
 
-.. code-block:: console
+After the build has succeded, your docs should be available in ``<output directory>/<branch>/index.html`` with a version selector menu/badge present.
 
-    $ sphinx-quickstart docs -p projectname -a author -v version --makefile --no-sep -r version -l en -q
-    $ git checkout -b feature_branch main  # Create new branch from main.
+.. note::
 
-    $ echo -e "Test\n====\n\nSample Documentation" > docs/index.rst  # Create one doc.
-    $ git add .
-    $ git commit -m "initial"
+    By default, ``sphinx-versioned-docs`` pre-builds the branches to see which of them fails; but this behaviour can be mitigated using the ``--no-prebuild`` argument.
 
-    $ sphinx-versioned
+.. note::
 
-------------------------------
+    Use ``--no-quite`` option to get output from the sphinx builder, adjust verbosity using ``-v``
+
+---------------------------
+
+Selecting/ Excluding branches and tags
+--------------------------------------
 
 By default, ``sphinx-versioned-docs`` will try to build all tags and branches present in the git repo.
-However, to build some particular branch(s) and tag(s), they can be specified in the ``--branches`` argument as:
+However, this behaviour can be augmented using the ``--branch`` command-line-argument, to build/exclude
+some particular branch(s) and tag(s), they can be specified in the ``--branch`` argument as:
 
-.. code-block:: console
+#. **For selecting a branch:** mention the branch/tag name in the CLI arugment like:
 
-    $ sphinx-versioned --branches "main, docs"
+    .. code-block:: console
 
-This command will build the ``main`` and ``docs`` branches.
-More such options are available at :ref:`options <settings>`.
+        $ sphinx-versioned --branch "main,v2.0"
+        $ sphinx-versioned --branch "+main,+v2.0"
 
+    Either of the two options above will select ``main``, ``v2.0`` and will only build these.
 
+#. **For excluding a branch:** mention the branch/tag name with ``-`` in the CLI argument like:
 
-After the build has succeded, your docs should be available in ``<output directory>/<branch>/index.html`` with a version selector menu/badge present.
+    .. code-block:: console
 
-.. note::
+        $ sphinx-versioned --branch "-main,-v2.0"
 
-    By default, ``sphinx-versioned-docs`` pre-builds the branches to see which of them fails; but this behaviour can be mitigated using the ``--no-prebuild`` argument.
+    The above command will build all available branches and tags except ``main``, ``v2.0``
 
-.. note::
+#. **For selecting and excluding simultaneously:** mention the branch/tag name with ``-`` in the CLI argument like:
 
-    Use ``--no-quite`` option to get output from the sphinx builder, adjust verbosity using ``-v``
+    .. code-block:: console
 
----------------------------
+        $ sphinx-versioned --branch "main,-v2.0"
+
+    The above command will only build ``main`` and will exclude ``-v2.0`` (untouched because the package was only building ``main``).
+
+More such options are available at :ref:`options <settings>`.
+
+------------------------------
 
 Deploy to github pages via github actions
 =========================================