7ad72dc84a
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>
250 lines
8.1 KiB
ReStructuredText
250 lines
8.1 KiB
ReStructuredText
=========================
|
|
OpenStack Sphinx themes
|
|
=========================
|
|
|
|
*openstackdocstheme* is a Sphinx documentation extension that includes
|
|
theme support for OpenStack Foundation projects.
|
|
|
|
The *openstackdocs* theme is used for documentation that is published
|
|
to docs.openstack.org and developer.openstack.org. It is intended for
|
|
use by OpenStack `projects governed by the Technical Committee`_.
|
|
|
|
The *starlingxdocs* theme is used for documentation that is published
|
|
to docs.starlingx.io. It is intended for use by StarlingX
|
|
`projects governed by the Technical Steering Committee`_.
|
|
|
|
.. _`projects governed by the Technical Committee`: https://governance.openstack.org/reference/projects/index.html
|
|
.. _`projects governed by the Technical Steering Committee`: https://docs.starlingx.io/governance/reference/projects/index.html
|
|
|
|
Using the theme
|
|
---------------
|
|
|
|
.. note::
|
|
|
|
Prior to using this theme, ensure your project can use the OpenStack brand
|
|
by referring to the brand guidelines at https://www.openstack.org/brand.
|
|
|
|
.. note::
|
|
|
|
Some of the settings below are included in the file generated by Sphinx when
|
|
you initialize a project, so they may already have values that need to be
|
|
changed.
|
|
|
|
#. Update the requirements list for your project to include
|
|
``openstackdocstheme`` (usually in ``test-requirements.txt``).
|
|
|
|
#. If your project previously used the *oslosphinx* theme (without modifying
|
|
the header navigation), remove ``oslosphinx`` from your requirements list,
|
|
and then in your ``conf.py`` you can remove the import statement and
|
|
extension listing for *oslosphinx*.
|
|
|
|
#. Once done, you should add ``'openstackdocstheme'`` to the list of extensions
|
|
Sphinx needs to initialize and configure the theme::
|
|
|
|
extensions = [
|
|
# ...
|
|
'openstackdocstheme',
|
|
# ...
|
|
]
|
|
|
|
html_theme = 'openstackdocs'
|
|
|
|
#. Set the options to link to the git repository on ``https://opendev.org`` and
|
|
bug tracker.
|
|
|
|
``openstackdocs_repo_name``
|
|
The prefix and repo name. For example,
|
|
``'openstack/python-glanceclient'``.
|
|
|
|
``openstackdocs_use_storyboard``
|
|
Set to ``True`` if using StoryBoard.
|
|
|
|
.. note::
|
|
|
|
If using StoryBoard, do not set ``bug_project`` and ``bug_tag``
|
|
options.
|
|
|
|
``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.
|
|
|
|
``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
|
|
openstackdocs_repo_name = 'openstack/python-glanceclient'
|
|
openstackdocs_bug_project = 'python-glanceclient'
|
|
openstackdocs_bug_tag = ''
|
|
|
|
One example for a project using StoryBoard::
|
|
|
|
# openstackdocstheme options
|
|
openstackdocs_repo_name = 'openstack/infra-manual'
|
|
openstackdocs_use_storyboard = true
|
|
|
|
#. Remove the options that will be automatically configured by the theme.
|
|
|
|
- ``project``
|
|
- ``html_last_updated_fmt``
|
|
|
|
#. 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``
|
|
|
|
#. (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 ``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
|
|
options were added.
|
|
|
|
.. versionchanged:: 1.20
|
|
|
|
In older versions of *openstackdocstheme*, it was necessary to manually
|
|
configure the ``html_last_updated_fmt`` option for HTML output and the
|
|
``latex_engine`` and ``latex_elements`` options if you required PDF output.
|
|
This is no longer the case as these attributes are now configured
|
|
automatically.
|
|
|
|
|
|
Additional Configuration
|
|
------------------------
|
|
|
|
If you are using this theme for API reference documentation, set the sidebar
|
|
navigation in the ``html_theme_options`` in the ``conf.py`` file::
|
|
|
|
# To use the API Reference sidebar dropdown menu,
|
|
# uncomment the html_theme_options parameter. The theme
|
|
# variable, sidebar_dropdown, should be set to `api_ref`.
|
|
# Otherwise, the list of links for the User and Ops docs
|
|
# appear in the sidebar dropdown menu.
|
|
html_theme_options = {
|
|
# ...
|
|
"sidebar_dropdown": "api_ref",
|
|
"sidebar_mode": "toc",
|
|
# ...
|
|
}
|
|
|
|
If you are using this theme for documentation you want to release based on git
|
|
tags on your repository, set the release dropdown menu option in the
|
|
``html_theme_options`` in the ``conf.py`` file. By default it is set to
|
|
``False``::
|
|
|
|
html_theme_options = {
|
|
# ...
|
|
"show_other_versions": "True",
|
|
# ...
|
|
}
|
|
|
|
If you are using this theme for a project with published documentation that
|
|
predates the Mitaka release cycle, set the earliest published version in the
|
|
``html_theme_options`` in the ``conf.py`` file to the name of the first series
|
|
with documentation available. By default it is set to ``None``::
|
|
|
|
html_theme_options = {
|
|
# ...
|
|
"earliest_published_series": "grizzly",
|
|
# ...
|
|
}
|
|
|
|
.. warning::
|
|
|
|
Do not use this for release-notes as they are always published as one
|
|
document with internal versioning.
|
|
|
|
|
|
A badge pointing out the support status of a document is shown now
|
|
for repositories that have ``stable/`` branches. The badge is not
|
|
displayed for api-ref, api-guide and releasenotes documents. It
|
|
can be disabled with the ``display_badge`` html theme option::
|
|
|
|
html_theme_options = {
|
|
# ...
|
|
"display_badge": False,
|
|
# ...
|
|
}
|
|
|
|
The TOC on the left contains a global section (to navigate between pages)
|
|
and a local section (showing page contents). If the TOC is displayed in the
|
|
text, you might want to disable the global section of the TOC::
|
|
|
|
html_theme_options = {
|
|
# ...
|
|
"display_global_toc_section": False,
|
|
# ...
|
|
}
|
|
|
|
If you are using this theme for something other than docs.openstack.org,
|
|
you can customize the root title ("OpenStack Docs") that appears in the
|
|
page title and the left arrow tooltip::
|
|
|
|
html_theme_options = {
|
|
# ...
|
|
"root_title": "OpenStack Governance",
|
|
# ...
|
|
}
|
|
|
|
External Link Helper
|
|
--------------------
|
|
|
|
The configuration option ``openstack_projects`` can be used to define
|
|
custom roles that build links that update automatically when branches
|
|
are created for each release series. Builds on the master branch link
|
|
to the ``latest`` documentation.
|
|
|
|
In the ``conf.py`` for the source documentation, add:
|
|
|
|
.. code-block:: python
|
|
|
|
openstack_projects = ['horizon']
|
|
|
|
Then in the documentation source, link to a target using syntax like:
|
|
|
|
.. code-block:: rst
|
|
|
|
:horizon-doc:`Launching Instances with Horizon <user/launch-instances.html>`
|
|
|
|
.. note::
|
|
|
|
Do not use this feature to reference projects that have a different branching
|
|
policy, for example, only have a master branch.
|
|
|
|
|
|
Demonstration example
|
|
---------------------
|
|
|
|
The demo documentation provides example output to ensure it matches what's
|
|
expected. The link below points to the example output when using the theme
|
|
for all documentation that is not API reference.
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
demo/index
|