Add package prefixes for all config options

It's bad practice to not prefix config options with a unique identifier
corresponding to the package. Start doing just this using the
'openstackdocs_' prefix.

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

doc/source/index.rst

@@ -49,14 +49,14 @@ Using the theme
 
      html_theme = 'openstackdocs'
 
-#. Set the options to link to the git repository on
-   ``https://opendev.org`` and bug tracker.
+#. Set the options to link to the git repository on ``https://opendev.org`` and
+   bug tracker.
 
-   ``repository_name``
+   ``openstackdocs_repo_name``
        The prefix and repo name. For example,
        ``'openstack/python-glanceclient'``.
 
-   ``use_storyboard``
+   ``openstackdocs_use_storyboard``
        Set to ``True`` if using StoryBoard.
 
        .. note::
@@ -64,27 +64,27 @@ Using the theme
           If using StoryBoard, do not set ``bug_project`` and ``bug_tag``
           options.
 
-   ``bug_project``
+   ``openstackdocs_bug_project``
        The project name or ID. For launchpad, it's a string like
        ``python-glanceclient``. If unspecified, the "Report a bug"
        links are not shown. This option can be removed if using StoryBoard.
 
-   ``bug_tag``
+   ``openstackdocs_bug_tag``
       Launchpad bug tag. If unspecified, no tag is set. The default is empty.
       This option can be removed if using StoryBoard.
 
    One example for a project using launchpad::
 
       # openstackdocstheme options
-      repository_name = 'openstack/python-glanceclient'
-      bug_project = 'python-glanceclient'
-      bug_tag = ''
+      openstackdocs_repo_name = 'openstack/python-glanceclient'
+      openstackdocs_bug_project = 'python-glanceclient'
+      openstackdocs_bug_tag = ''
 
    One example for a project using StoryBoard::
 
       # openstackdocstheme options
-      repository_name = 'openstack/infra-manual'
-      use_storyboard = True
+      openstackdocs_repo_name = 'openstack/infra-manual'
+      openstackdocs_use_storyboard = true
 
 #. Remove the options that will be automatically configured by the theme.
 
@@ -111,6 +111,14 @@ Using the theme
    ``openstackdocs_auto_name`` option to ``false`` and configuring the
    ``project`` option to the name you wish to use.
 
+.. versionchanged:: 2.1.0
+
+   The ``repository_name``, ``bug_project``, ``bug_tag`` and ``use_storyboard``
+   config options were renamed to ``openstackdocs_repo_name``,
+   ``openstackdocs_bug_project``, ``openstackdocs_bug_tag`` and
+   ``openstackdocs_use_storyboard``, respectively. Aliases are provided but
+   these will be removed in a future release.
+
 .. versionchanged:: 2.1.0
 
    The ``openstackdocs_auto_version`` and ``openstackdocs_auto_name`` config

openstackdocstheme/ext.py

@@ -111,6 +111,35 @@ def _html_page_context(app, pagename, templatename, context, doctree):
     global _html_context_data
     if _html_context_data is None:
         logger.debug('[openstackdocstheme] building html context')
+
+        if app.config.repository_name is not None:
+            logger.info(
+                "The 'repository_name' config option has been deprecated and "
+                "replaced by the 'openstackdocs_repo_name' option; support "
+                "for the former will be dropped in a future release")
+            app.config.openstackdocs_repo_name = app.config.repository_name
+
+        if app.config.use_storyboard is not None:
+            logger.info(
+                "The 'use_storyboard' config option has been deprecated and "
+                "replaced by the 'openstackdocs_use_storyboard' option; "
+                "support for the former will be dropped in a future release")
+            app.config.openstackdocs_use_storyboard = app.config.use_storyboard
+
+        if app.config.bug_project is not None:
+            logger.info(
+                "The 'bug_project' config option has been deprecated and "
+                "replaced by the 'openstackdocs_bug_project' option; support "
+                "for the former will be dropped in a future release")
+            app.config.openstackdocs_bug_project = app.config.bug_project
+
+        if app.config.bug_tag is not None:
+            logger.info(
+                "The 'bug_tag' config option has been deprecated and "
+                "replaced by the 'openstackdocs_bug_tag' option; support "
+                "for the former will be dropped in a future release")
+            app.config.openstackdocs_bug_project = app.config.bug_project
+
         _html_context_data = {}
         try:
             _html_context_data['gitsha'] = subprocess.check_output(
@@ -121,16 +150,16 @@ def _html_page_context(app, pagename, templatename, context, doctree):
             _html_context_data['gitsha'] = 'unknown'
 
         doc_path = _get_doc_path(app)
-        repo_name = app.config.repository_name
+        repo_name = app.config.openstackdocs_repo_name
         _html_context_data['repository_name'] = repo_name
         logger.debug('[openstackdocstheme] repository_name %r', repo_name)
         if repo_name and doc_path:
             _html_context_data['giturl'] = _giturl.format(repo_name, doc_path)
             logger.info('[openstackdocstheme] giturl %r',
                         _html_context_data['giturl'])
-        use_storyboard = app.config.use_storyboard
+        use_storyboard = app.config.openstackdocs_use_storyboard
         _html_context_data['use_storyboard'] = use_storyboard
-        bug_project = app.config.bug_project
+        bug_project = app.config.openstackdocs_bug_project
         if bug_project:
             logger.info('[openstackdocstheme] bug_project (from user) %r',
                         bug_project)
@@ -147,7 +176,7 @@ def _html_page_context(app, pagename, templatename, context, doctree):
             logger.info('[openstackdocstheme] bug_project looks like a '
                         'number, setting use_storyboard')
             _html_context_data['use_storyboard'] = True
-        bug_tag = app.config.bug_tag
+        bug_tag = app.config.openstackdocs_bug_tag
         if bug_tag:
             _html_context_data['bug_tag'] = bug_tag
             logger.info('[openstackdocstheme] bug_tag %r', bug_tag)
@@ -212,7 +241,7 @@ def _get_series_name():
 
 def _setup_link_roles(app):
     series = _get_series_name()
-    for project_name in app.config.openstack_projects:
+    for project_name in app.config.openstackdocs_projects:
         url = 'https://docs.openstack.org/{}/{}/%s'.format(
             project_name, series)
         role_name = '{}-doc'.format(project_name)
@@ -274,6 +303,14 @@ def _get_project_name(srcdir):
 def _builder_inited(app):
     theme_dir = paths.get_html_theme_path()
     logger.info('Using openstackdocstheme Sphinx theme from %s' % theme_dir)
+
+    if app.config.openstack_projects is not None:
+        logger.info(
+            "The 'openstack_projects' config option has been deprecated and "
+            "replaced by the 'openstackdocs_projects' option; support "
+            "for the former will be dropped in a future release")
+        app.config.openstackdocs_projects = app.config.openstack_projects
+
     _setup_link_roles(app)
 
     # we only override configuration if the theme has been configured, meaning
@@ -369,15 +406,28 @@ def _builder_inited(app):
 
 def setup(app):
     logger.info('connecting events for openstackdocstheme')
+
+    # extensions
     app.connect('builder-inited', _builder_inited)
     app.connect('html-page-context', _html_page_context)
-    app.add_config_value('repository_name', '', 'env')
-    app.add_config_value('bug_project', '', 'env')
-    app.add_config_value('bug_tag', '', 'env')
-    app.add_config_value('openstack_projects', [], 'env')
-    app.add_config_value('use_storyboard', False, 'env')
+
+    # config options
+    app.add_config_value('openstackdocs_repo_name', '', 'env')
+    app.add_config_value('openstackdocs_bug_project', '', 'env')
+    app.add_config_value('openstackdocs_bug_tag', '', 'env')
+    app.add_config_value('openstackdocs_projects', [], 'env')
+    app.add_config_value('openstackdocs_use_storyboard', False, 'env')
     app.add_config_value('openstackdocs_auto_version', None, 'env')
     app.add_config_value('openstackdocs_auto_name', True, 'env')
+
+    # legacy config options
+    app.add_config_value('repository_name', None, 'env')
+    app.add_config_value('bug_project', None, 'env')
+    app.add_config_value('bug_tag', None, 'env')
+    app.add_config_value('openstack_projects', None, 'env')
+    app.add_config_value('use_storyboard', None, 'env')
+
+    # themes
     app.add_html_theme(
         'openstackdocs',
         os.path.abspath(os.path.dirname(__file__)) + '/theme/openstackdocs',
@@ -386,6 +436,7 @@ def setup(app):
         'starlingxdocs',
         os.path.abspath(os.path.dirname(__file__)) + '/theme/starlingxdocs',
     )
+
     return {
         'parallel_read_safe': True,
     }

releasenotes/notes/renamed-opts-bbf5d1390ed6ba71.yaml

@@ -0,0 +1,15 @@
+---
+upgrade:
+  - |
+    All configuration options are now prefixed with ``openstackdocs_``. Support
+    for the previous configuration option names are considered deprecated and
+    will be removed in a future release.
+
+    .. csv-table:: Affected options
+       :header: "New Name", "Deprecated Name"
+
+       ``openstackdocs_repo_name``, ``repository_name``
+       ``openstackdocs_use_storyboard``, ``use_storyboard``
+       ``openstackdocs_bug_project``, ``bug_project``
+       ``openstackdocs_bug_tag``, ``bug_tag``
+       ``openstackdocs_project``, ``openstack_project``