Add 'openstackdocs_auto_version' config option, path checking

Rather than relying on magic values to determine whether we should
attempt to auto-version documentation, start checking the paths for
commonly unversioned source doc paths and add an explicit knob to turn
this on or off.

Change-Id: Iecc3fa6f20f1aa92fcffe2b8adb0cd0da1aa17e4
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Closes-Bug: #1843976

doc/source/index.rst

@@ -93,12 +93,23 @@ Using the theme
    - ``latex_engine``
    - ``latex_elements``
 
-   In addition, if your documentation is versioned, you should remove the
-   options related to versioning.
+#. Configure version-related options.
+
+   For everything except documentation in the ``api-guide``, ``api-ref``, and
+   ``releasenotes`` paths, the theme will automatically set the version of your
+   documentation. This behavior can be manually configured by setting the
+   ``openstackdocs_auto_version`` option to either ``True`` or ``False``.
+
+   If your documentation is auto-versioned, you should remove the options
+   related to versioning as they will be overridden.
 
    - ``version``
    - ``release``
 
+.. versionchanged:: 2.1.0
+
+   The ``openstackdocs_auto_version`` config option was added.
+
 .. versionchanged:: 1.20
 
    In older versions of *openstackdocstheme*, it was necessary to manually

openstackdocstheme/ext.py

@@ -284,10 +284,6 @@ def _builder_inited(app):
     # to a 'config-inited' handler
 
     project_name = _get_project_name(app.srcdir)
-    try:
-        version = packaging.get_version(project_name)
-    except Exception:
-        version = None
 
     # NOTE(stephenfin): Chances are that whatever's in 'conf.py' is probably
     # wrong/outdated so, if we can, we intentionally overwrite it...
@@ -296,11 +292,45 @@ def _builder_inited(app):
 
     app.config.html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
-    # ...except for version/release which, if blank, should remain that way to
-    # cater for unversioned documents
-    if app.config.version != '' and version:
-        app.config.version = version
-        app.config.release = version
+    if app.config.openstackdocs_auto_version is False:
+        logger.info(
+            '[openstackdocstheme] auto-versioning disabled (configured by '
+            'user)'
+        )
+        auto_version = False
+    elif app.config.openstackdocs_auto_version is True:
+        logger.info(
+            '[openstackdocstheme] auto-versioning enabled (configured by user)'
+        )
+        auto_version = True
+    else:  # None
+        doc_parts = os.path.abspath(app.srcdir).split(os.sep)[-2:]
+        if doc_parts[0] in ('api-guide', 'api-ref', 'releasenotes'):
+            logger.info(
+                f'[openstackdocstheme] auto-versioning disabled (doc name '
+                f'contains {doc_parts[0]}'
+            )
+            auto_version = False
+        else:
+            logger.info(
+                '[openstackdocstheme] auto-versioning enabled (default)'
+            )
+            auto_version = True
+
+    if auto_version:
+        try:
+            project_version = packaging.get_version(project_name)
+        except Exception:
+            project_version = None
+
+        if not project_version:
+            logger.warning(
+                'Could not extract version from project; defaulting to '
+                'unversioned'
+            )
+
+        app.config.version = project_version
+        app.config.release = project_version
 
     theme_logo = paths.get_theme_logo_path(app.config.html_theme)
     pdf_theme_path = paths.get_pdf_theme_path(app.config.html_theme)
@@ -326,6 +356,7 @@ def setup(app):
     app.add_config_value('bug_tag', '', 'env')
     app.add_config_value('openstack_projects', [], 'env')
     app.add_config_value('use_storyboard', False, 'env')
+    app.add_config_value('openstackdocs_auto_version', None, 'env')
     app.add_html_theme(
         'openstackdocs',
         os.path.abspath(os.path.dirname(__file__)) + '/theme/openstackdocs',

releasenotes/notes/add-openstackdocs_auto_version-option-fd03f20373eede39.yaml

@@ -0,0 +1,13 @@
+---
+features:
+  - |
+    A new config option, ``openstackdocs_auto_version``, has been added. This
+    can be used to disable auto-versioning of documentation for things like
+    release notes or API references.
+upgrade:
+  - |
+    The ``openstackdocs_auto_version`` option must be configured to disable
+    auto-versioning of documentation. Previously, the extension would check for
+    an empty string (``''``) and, if present, use this to indicate that the
+    document should be unversioned. However, this only worked if building
+    documentation using the ``build_sphinx`` distutils extension.