Merge pull request #7 from Holzhaus/override-paths-via-defines

Allow variable substitution in command line defines

docs/changelog.rst

@@ -4,6 +4,12 @@
 Changelog
 =========
 
+Version 0.2
+===========
+
+* Added a way to override config variables using placeholders that expand to each version's actual value (`#4 <issue4_>`_, `#7 <issue7_>`_).
+
+
 Version 0.1
 ===========
 
@@ -17,3 +23,7 @@ Version 0.1.0
 -------------
 
 * Initial release
+
+
+.. _issue4: https://github.com/Holzhaus/sphinx-multiversion/issues/4
+.. _issue7: https://github.com/Holzhaus/sphinx-multiversion/issues/7

docs/conf.py

@@ -4,8 +4,8 @@ import time
 
 author = "Jan Holthuis"
 project = "sphinx-multiversion"
-release = "0.1.1"
-version = "0.1"
+release = "0.2.0"
+version = "0.2"
 copyright = "{}, {}".format(time.strftime("%Y"), author)
 
 html_last_updated_fmt = "%c"
@@ -30,4 +30,5 @@ html_sidebars = {
     ],
 }
 
-mv_remote_whitelist = r"^origin$"
+smv_remote_whitelist = r"^origin$"
+smv_branch_whitelist = r"^master$"

docs/configuration.rst

@@ -107,5 +107,30 @@ Here are some examples:
     Have a look at `PyFormat <python_format_>`_ for information how to use new-stye Python formatting.
 
 
+Overriding Configuration Variables
+==================================
+
+You can override configuration variables the same way as you're used to with ``sphinx-build``.
+
+Since ``sphinx-multiversion`` copies the branch data into a temporary directory and builds them there while leaving the current working directory unchanged, relative paths in your :file:`conf.py` will refer to the path of the version *you're building from*, not the path of the version you are trying to build documentation for.
+
+Sometimes it might be necessary to override the configured path via a command line overide.
+``sphinx-multiversion`` allows you to insert placeholders into your override strings that will automatically be replaced with the correct value for the version you're building the documentation for.
+
+Here's an example for the `exhale extension <exhale_>`_:
+
+.. code-block:: python
+
+    sphinx-multiversion docs build/html -D 'exhale_args.containmentFolder=${sourcedir}/api'
+
+.. note::
+
+    Make sure to enclose the override string in single quotes (``'``) to prevent the shell from treating it as an environment variable and replacing it before it's passed to ``sphinx-multiversion``.
+
+.. note::
+
+    To see a list of available placeholder names and their values for each version you can use the ``--dump-metadata`` flag.
+
 .. _python_regex: https://docs.python.org/3/howto/regex.html
 .. _python_format: https://pyformat.info/
+.. _exhale: https://exhale.readthedocs.io/en/latest/

setup.py

@@ -20,7 +20,7 @@ setup(
     author="Jan Holthuis",
     author_email="[email protected]",
     url="https://holzhaus.github.io/sphinx-multiversion/",
-    version="0.1.1",
+    version="0.2.0",
     install_requires=["sphinx >= 2.1"],
     license="BSD",
     packages=["sphinx_multiversion"],

sphinx_multiversion/main.py

@@ -6,6 +6,7 @@ import logging
 import os
 import pathlib
 import re
+import string
 import subprocess
 import sys
 import tempfile
@@ -179,7 +180,10 @@ def main(argv=None):
                 "source": gitref.source,
                 "creatordate": gitref.creatordate.strftime(sphinx.DATE_FMT),
                 "sourcedir": current_sourcedir,
-                "outputdir": outputdir,
+                "outputdir": os.path.join(
+                    os.path.abspath(args.outputdir), outputdir
+                ),
+                "confdir": os.path.abspath(confdir),
                 "docnames": list(project.discover()),
             }
 
@@ -199,22 +203,29 @@ def main(argv=None):
         # Run Sphinx
         argv.extend(["-D", "smv_metadata_path={}".format(metadata_path)])
         for version_name, data in metadata.items():
-            outdir = os.path.join(args.outputdir, data["outputdir"])
-            os.makedirs(outdir, exist_ok=True)
+            os.makedirs(data["outputdir"], exist_ok=True)
+
+            defines = itertools.chain(
+                *(
+                    ("-D", string.Template(d).safe_substitute(data))
+                    for d in args.define
+                )
+            )
 
             current_argv = argv.copy()
             current_argv.extend(
                 [
-                    *itertools.chain(*(("-D", d) for d in args.define)),
+                    *defines,
                     "-D",
                     "smv_current_version={}".format(version_name),
                     "-c",
-                    confdir,
+                    data["confdir"],
                     data["sourcedir"],
-                    outdir,
+                    data["outputdir"],
                     *args.filenames,
                 ]
             )
+            logger.debug("Running sphinx-build with args: %r", current_argv)
             status = sphinx_build.build_main(current_argv)
             if status not in (0, None):
                 break