diff --git a/docs/changelog.rst b/docs/changelog.rst index 1c33a39..54e1179 100644 --- a/docs/changelog.rst +++ b/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 `_, `#7 `_). + + 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 diff --git a/docs/conf.py b/docs/conf.py index 6d3064a..7fd51c0 100644 --- a/docs/conf.py +++ b/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$" diff --git a/docs/configuration.rst b/docs/configuration.rst index a6f5160..af5fad9 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -107,5 +107,30 @@ Here are some examples: Have a look at `PyFormat `_ 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 `_: + +.. 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/ diff --git a/setup.py b/setup.py index 4827ca9..469533b 100755 --- a/setup.py +++ b/setup.py @@ -20,7 +20,7 @@ setup( author="Jan Holthuis", author_email="holthuis.jan@googlemail.com", 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"], diff --git a/sphinx_multiversion/main.py b/sphinx_multiversion/main.py index 5224a08..657c918 100644 --- a/sphinx_multiversion/main.py +++ b/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