1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
===========================================
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 your project uses
``storyboard.openstack.org``, use the project number instead like
``901``. If unspecified, the "Report a bug" links are not shown.
``bug_tag``
Launchpad bug tag. If unspecified, no tag is set. The default is empty.
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 = '721'
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.
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
|
