The contentes of this PR

sphinx-contrib/multiversion#62

has not been merged yet and is not available from pypi.

This picks-up that change to that `smv_prebuild_command`
can be used by Zuar documentation.

README.md

@@ -1,8 +1,8 @@
-# sphinx-multiversion [![Build Status](https://travis-ci.org/Holzhaus/sphinx-multiversion.svg?branch=master)](https://travis-ci.org/Holzhaus/sphinx-multiversion)
-
 Sphinx extension for building self-hosted versioned docs.
 
-This extension aims to provide a clean implementation that tries to avoid
-messing with Sphinx internals as much as possible.
+This is a Zuar fork of the original `sphinx-multiversion`, which
+lives here:  https://holzhaus.github.io/sphinx-multiversion/
 
-Documentation can be found at: https://holzhaus.github.io/sphinx-multiversion/
+The fork is necessary to add support for `smv_prebuild_command` which
+is not yet available in the original repo.  This fork can be
+removed once the prebuild feature is available via pypi.

docs/configuration.rst

@@ -82,6 +82,18 @@ Here are some examples:
         git for-each-ref --format "%(refname)" | sed 's/^refs\///g'
 
 
+Prebuild command
+================
+
+In some cases it may be necessary to run a command in the checked out
+directory before building with sphinx. For example if you are using
+``sphinx-apidoc`` to generate the autodoc api source files.
+
+For example:
+
+    smv_prebuild_command = "sphinx-apidoc -o docs/api mymodule"
+
+
 Output Directory Format
 =======================
 

sphinx_multiversion/main.py

@@ -67,6 +67,7 @@ def load_sphinx_config_worker(q, confpath, confoverrides, add_defaults):
                 str,
             )
             current_config.add("smv_prefer_remote_refs", False, "html", bool)
+            current_config.add("smv_prebuild_command", "", "html", str)
         current_config.pre_init_values()
         current_config.init_values()
     except Exception as err:
@@ -289,6 +290,7 @@ def main(argv=None):
                 ),
                 "confdir": confpath,
                 "docnames": list(project.discover()),
+                "commit": gitref.commit,
             }
 
         if args.dump_metadata:
@@ -329,16 +331,37 @@ def main(argv=None):
                     *args.filenames,
                 ]
             )
-            logger.debug("Running sphinx-build with args: %r", current_argv)
+
+            current_cwd = os.path.join(data["basedir"], cwd_relative)
+
+            env = os.environ.copy()
+
+            if config.smv_prebuild_command != "":
+                logger.info("Running prebuild command: %r", config.smv_prebuild_command)
+
+                cpi = subprocess.run(
+                    config.smv_prebuild_command,
+                    cwd=current_cwd,
+                    shell=True,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.STDOUT,
+                    env=env,
+                    executable="/bin/bash",
+                )
+
+                if cpi.returncode != 0:
+                    print(cpi.stdout.decode("UTF-8"), file=sys.stderr, flush=True)
+                    raise subprocess.CalledProcessError
+
+            logger.info("Running sphinx-build with args: %r", current_argv)
             cmd = (
                 sys.executable,
                 *get_python_flags(),
                 "-m",
                 "sphinx",
                 *current_argv,
             )
-            current_cwd = os.path.join(data["basedir"], cwd_relative)
-            env = os.environ.copy()
+
             env.update(
                 {
                     "SPHINX_MULTIVERSION_NAME": data["name"],

sphinx_multiversion/sphinx.py

@@ -27,6 +27,7 @@
         "version",
         "release",
         "is_released",
+        "commit",
     ],
 )
 
@@ -45,6 +46,7 @@ def _dict_to_versionobj(self, v):
             version=v["version"],
             release=v["release"],
             is_released=v["is_released"],
+            commit=v["commit"],
         )
 
     @property