From b4b5cc6281343f92ccb39be46d59982fb9d3d2f5 Mon Sep 17 00:00:00 2001 From: Jan Holthuis Date: Sat, 11 Apr 2020 03:12:43 +0200 Subject: [PATCH 1/7] Allow variable substitution in command line defines Attempt to fix edge cases where other extensions need to know about the actual source path. Resolves: #4 --- sphinx_multiversion/main.py | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/sphinx_multiversion/main.py b/sphinx_multiversion/main.py index 5224a08d..2b99a8f6 100644 --- a/sphinx_multiversion/main.py +++ b/sphinx_multiversion/main.py @@ -6,6 +6,7 @@ import os import pathlib import re +import string import subprocess import sys import tempfile @@ -199,22 +200,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) + data["confdir"] = confdir + data["outputdir"] = os.path.join(args.outputdir, data["outputdir"]) + 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 From a21fa854c77d13fc7c9437f2fc64f85e4026fbce Mon Sep 17 00:00:00 2001 From: Jan Holthuis Date: Wed, 15 Apr 2020 14:20:00 +0200 Subject: [PATCH 2/7] sphinx_multiversion/main: Reformat CLI define substitution --- sphinx_multiversion/main.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/sphinx_multiversion/main.py b/sphinx_multiversion/main.py index 2b99a8f6..19013c11 100644 --- a/sphinx_multiversion/main.py +++ b/sphinx_multiversion/main.py @@ -204,10 +204,12 @@ def main(argv=None): data["outputdir"] = os.path.join(args.outputdir, data["outputdir"]) os.makedirs(data["outputdir"], exist_ok=True) - defines = itertools.chain(*( - ("-D", string.Template(d).safe_substitute(data)) - for d in args.define - )) + defines = itertools.chain( + *( + ("-D", string.Template(d).safe_substitute(data)) + for d in args.define + ) + ) current_argv = argv.copy() current_argv.extend( From 75e8b3f96bce8959a8c0bd2e1c9cadcfbf3b02d9 Mon Sep 17 00:00:00 2001 From: Jan Holthuis Date: Wed, 15 Apr 2020 14:20:51 +0200 Subject: [PATCH 3/7] Add absolute outputdir and confdir to metadata dict --- sphinx_multiversion/main.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/sphinx_multiversion/main.py b/sphinx_multiversion/main.py index 19013c11..657c9188 100644 --- a/sphinx_multiversion/main.py +++ b/sphinx_multiversion/main.py @@ -180,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()), } @@ -200,8 +203,6 @@ def main(argv=None): # Run Sphinx argv.extend(["-D", "smv_metadata_path={}".format(metadata_path)]) for version_name, data in metadata.items(): - data["confdir"] = confdir - data["outputdir"] = os.path.join(args.outputdir, data["outputdir"]) os.makedirs(data["outputdir"], exist_ok=True) defines = itertools.chain( From 061328974713b59334825cfa0e83c42f6f961651 Mon Sep 17 00:00:00 2001 From: Jan Holthuis Date: Sun, 19 Apr 2020 12:41:31 +0200 Subject: [PATCH 4/7] docs/configuration: Add documentation for overriding with placeholders --- docs/configuration.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/configuration.rst b/docs/configuration.rst index a6f5160c..af5fad99 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/ From d6712690f22ebc6b50a5df5014e4ec6c5d4974c6 Mon Sep 17 00:00:00 2001 From: Jan Holthuis Date: Sun, 19 Apr 2020 12:42:07 +0200 Subject: [PATCH 5/7] Bump version to 0.2.0 and add changelog entry for PR #7 --- docs/changelog.rst | 10 ++++++++++ docs/conf.py | 4 ++-- setup.py | 2 +- 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 1c33a392..54e11790 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 6d3064a7..a195a8a6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,8 +4,8 @@ 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" diff --git a/setup.py b/setup.py index 4827ca99..469533bf 100755 --- a/setup.py +++ b/setup.py @@ -20,7 +20,7 @@ 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"], From 25762bac4c7c3b3bc0d716a7e76ca6f7aa2a862d Mon Sep 17 00:00:00 2001 From: Jan Holthuis Date: Sun, 19 Apr 2020 12:44:20 +0200 Subject: [PATCH 6/7] docs/conf: Fix remote whitelists --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index a195a8a6..b54d8c51 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,4 +30,4 @@ ], } -mv_remote_whitelist = r"^origin$" +smv_remote_whitelist = r"^origin$" From 9a4c4d27d5ba3530945a4896f5752faaa9ef297f Mon Sep 17 00:00:00 2001 From: Jan Holthuis Date: Sun, 19 Apr 2020 12:58:42 +0200 Subject: [PATCH 7/7] docs/conf: Do not build docs for development branches --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index b54d8c51..7fd51c08 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,3 +31,4 @@ } smv_remote_whitelist = r"^origin$" +smv_branch_whitelist = r"^master$"