diff --git a/doc/source/index.rst b/doc/source/index.rst index 65d43728..ae130883 100644 --- a/doc/source/index.rst +++ b/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 diff --git a/openstackdocstheme/ext.py b/openstackdocstheme/ext.py index f0a3a16d..5f0edbe0 100644 --- a/openstackdocstheme/ext.py +++ b/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, } diff --git a/releasenotes/notes/renamed-opts-bbf5d1390ed6ba71.yaml b/releasenotes/notes/renamed-opts-bbf5d1390ed6ba71.yaml new file mode 100644 index 00000000..0a0b3964 --- /dev/null +++ b/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``