Parsing conf.py to enable configuration file arguments

docs/changes/78.breaking.rst

@@ -0,0 +1 @@
+Selecting a branch will take precedence over excluding one.

docs/changes/78.feature.rst

@@ -0,0 +1,4 @@
+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.

docs/settings.rst

@@ -10,17 +10,9 @@ Settings
 
 The ``sphinx-versioned-docs`` reads options from two sources:
 
-    * From the sphinx ``conf.py`` file.
     * From the provided command-line-arguments.
+    * From the sphinx ``conf.py`` file.
 
-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: <url>
-
-    Setting this variable will make sure that the ``Project home`` is listed on the versions selector badge/menu.
 
 Command Line Arguments
 ======================
@@ -64,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 <branch name>, --main-branch <branch name>
 
     Specify the main-branch to which the top-level ``index.html`` redirects to. Default is ``main``.
@@ -72,6 +68,14 @@ 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`.
@@ -92,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: <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 ``|`` and supports regex.
+
+    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 <https://github.com/devanshshukla99/sphinx-versioned-docs/issues/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

sphinx_versioned/__main__.py

@@ -1,12 +1,10 @@
-import re
 import sys
 import typer
 
 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)
 
@@ -61,6 +59,11 @@ 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`."
     ),
@@ -73,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]",
@@ -104,51 +107,54 @@ 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`
         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:`bool`
         Force branch selection. Use this option to build detached head/commits. [Default = `False`]
 
     Returns
     -------
     :class:`sphinx_versioned.build.VersionedDocs`
     """
-    logger_format = "| <level>{level: <8}</level> | - <level>{message}</level>"
-
+    # Logger init
     log.remove()
+    logger_format = "| <level>{level: <8}</level> | - <level>{message}</level>"
     log.add(sys.stderr, format=logger_format, level=loglevel.upper())
 
-    select_branches, exclude_branches = 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
+    # Parse --branch into either select/exclude variables
+    select_branch, exclude_branch = parse_branch_selection(branches)
 
-    if sphinx_compatibility:
-        mp_sphinx_compatibility()
+    config = {
+        "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,
+        "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}
 
-    return VersionedDocs(
-        {
-            "chdir": chdir,
-            "output_dir": output_dir,
-            "git_root": git_root,
-            "local_conf": local_conf,
-            "prebuild_branches": prebuild,
-            "select_branches": select_branches,
-            "exclude_branches": exclude_branches,
-            "main_branch": main_branch,
-            "quite": quite,
-            "verbose": verbose,
-            "force_branches": force_branches,
-        }
+    # VersionedDocs instance
+    DocsBuilder = VersionedDocs(
+        chdir=chdir,
+        git_root=git_root,
+        local_conf=local_conf,
+        output_dir=output_dir,
+        config=filtered_config,
+        ignore_conf=ignore_conf,
     )
+    return DocsBuilder.run()
 
 
 if __name__ == "__main__":