Add 'openstackdocs_auto_name' config option

As we recently did with auto-versioning, make the setting of the package
name configurable.

Change-Id: Ia9f6dab3fe86b2fc7d6b54f81230b3b9723e5e03
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

doc/source/index.rst

@@ -106,9 +106,17 @@ Using the theme
    - ``version``
    - ``release``
 
+#. (Optional) Manually configure the project name.
+
+   The theme will automatically set the project name used in your
+   documentation. You can disable this behavior by setting the
+   ``openstackdocs_auto_name`` option to ``false`` and configuring the
+   ``project`` option to the name you wish to use.
+
 .. versionchanged:: 2.1.0
 
-   The ``openstackdocs_auto_version`` config option was added.
+   The ``openstackdocs_auto_version`` and ``openstackdocs_auto_name`` config
+   options were added.
 
 .. versionchanged:: 1.20
 

openstackdocstheme/ext.py

@@ -283,12 +283,19 @@ def _builder_inited(app):
     # TODO(stephenfin): Once Sphinx 1.8 is released, we should move the below
     # to a 'config-inited' handler
 
-    project_name = _get_project_name(app.srcdir)
+    if app.config.openstackdocs_auto_name:
+        project_name = _get_project_name(app.srcdir)
 
-    # NOTE(stephenfin): Chances are that whatever's in 'conf.py' is probably
-    # wrong/outdated so, if we can, we intentionally overwrite it...
-    if project_name:
-        app.config.project = project_name
+        if app.config.project and project_name:
+            logger.info(
+                "Overriding configured project name (%s) with name extracted "
+                "from the package (%s); you can disable this behavior with "
+                "the 'openstackdocs_auto_name' option",
+                app.config.project, project_name,
+            )
+
+        if project_name:
+            app.config.project = project_name
 
     app.config.html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
@@ -357,6 +364,7 @@ def setup(app):
     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_config_value('openstackdocs_auto_name', True, 'env')
     app.add_html_theme(
         'openstackdocs',
         os.path.abspath(os.path.dirname(__file__)) + '/theme/openstackdocs',

releasenotes/notes/add-openstackdocs_auto_name-option-efbd1cf9a171f079.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    A new config option, ``openstackdocs_auto_name``, has been added. This
+    can be used to disable auto-configuration of the project name through
+    inspection of package metadata.