193 lines
5.8 KiB
ReStructuredText
193 lines
5.8 KiB
ReStructuredText
===========================================
|
|
OpenStack docs.openstack.org Sphinx theme
|
|
===========================================
|
|
|
|
*openstackdocstheme* is a theme and extension support for Sphinx 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`_.
|
|
|
|
.. _`projects governed by the Technical Committee`: https://governance.openstack.org/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 and bug tracker.
|
|
|
|
``repository_name``
|
|
The prefix and repo name. For example,
|
|
``'openstack/python-glanceclient'``.
|
|
|
|
``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.
|
|
|
|
If your project uses ``storyboard.openstack.org``, it's a
|
|
string like ``openstack-ci`` for the project group.
|
|
|
|
..note:: Previously StoryBoard showed numbers, and thus you set
|
|
this to a project number instead like ``901``. Set this to a
|
|
string instead and also use the ``use_storyboard`` variable.
|
|
|
|
``bug_tag``
|
|
Launchpad bug tag. If unspecified, no tag is set. The default is empty.
|
|
|
|
``use_storyboard``
|
|
Set to ``True`` if using StoryBoard.
|
|
|
|
One example for a project using launchpad::
|
|
|
|
# openstackdocstheme options
|
|
repository_name = 'openstack/python-glanceclient'
|
|
bug_project = 'python-glanceclient'
|
|
bug_tag = ''
|
|
|
|
One example for a project using StoryBoard::
|
|
|
|
# openstackdocstheme options
|
|
repository_name = 'openstack-infra/infra-manual'
|
|
bug_project = 'openstack-ci'
|
|
bug_tag = ''
|
|
|
|
#. Remove the options that will be automatically configured by the theme.
|
|
|
|
- ``project``
|
|
- ``html_last_updated_fmt``
|
|
- ``latex_engine``
|
|
- ``latex_elements``
|
|
|
|
In addition, if your documentation is versioned, you should remove the
|
|
options related to versioning.
|
|
|
|
- ``version``
|
|
- ``release``
|
|
|
|
.. 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.
|
|
|
|
|
|
By default, a badge is displayed showing which the latest OpenStack
|
|
release is. You can disable the badge with::
|
|
|
|
html_theme_options = {
|
|
# ...
|
|
"display_badge": False,
|
|
# ...
|
|
}
|
|
|
|
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>`
|
|
|
|
|
|
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
|