diff --git a/docs/configuration.rst b/docs/configuration.rst index 6b7d6aa2..c865d55f 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -130,6 +130,28 @@ Here's an example for the `exhale extension `_: To see a list of available placeholder names and their values for each version you can use the ``--dump-metadata`` flag. +Running Commands Before Building +================================ + +You can run commands before each version of the documentation is built with the option ``--pre-build``. + +This could be useful to prepare the docs repository before running ``sphinx-build``, debug the execution, or even generate versioned documentation using other builders. + +For example, imagine that you want to build versioned docs written in Sphinx, but the API reference is generated with JavaDoc. This option enables the generation of both versioned docs to host them under the same folder using GitHub Pages. + +Here's an example showing the directory where the build command is running: + +.. code-block:: python + + sphinx-multiversion docs build/html --pre-build pwd + + +You can pass multiple commands by adding extra ``--pre-build`` tags. The commands run in order, from left to right: + +.. code-block:: python + + sphinx-multiversion docs build/html --pre-build pwd --pre-build ls + .. _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/sphinx_multiversion/main.py b/sphinx_multiversion/main.py index 86766e2d..da41d381 100644 --- a/sphinx_multiversion/main.py +++ b/sphinx_multiversion/main.py @@ -12,6 +12,7 @@ import subprocess import sys import tempfile +import shlex from sphinx import config as sphinx_config from sphinx import project as sphinx_project @@ -159,6 +160,12 @@ def main(argv=None): action="store_true", help="dump generated metadata and exit", ) + parser.add_argument( + "--pre-build", + action="append", + default=[], + help="a list of commands to run before running sphinx-build", + ) args, argv = parser.parse_known_args(argv) if args.noconfig: return 1 @@ -183,6 +190,9 @@ def main(argv=None): confdir_absolute, confoverrides, add_defaults=True ) + # Parse pre build commands + pre_build_commands = [shlex.split(command) for command in args.pre_build] + # Get relative paths to root of git repository gitroot = pathlib.Path( git.get_toplevel_path(cwd=sourcedir_absolute) @@ -346,6 +356,12 @@ def main(argv=None): "SPHINX_MULTIVERSION_CONFDIR": data["confdir"], } ) + + if pre_build_commands: + logger.debug("Running pre build commands:") + for command in pre_build_commands: + subprocess.check_call(command, cwd=current_cwd, env=env) + subprocess.check_call(cmd, cwd=current_cwd, env=env) return 0