Configure additional properties
Configure the 'html_last_updated_fmt', 'latex_engine' and 'latex_elements' attributes automatically. Documentation is updated to reflect the fact that these no longer need to be configured by hand. Change-Id: I429b981135e35845bf5ed70020abfef3deccbf90
This commit is contained in:
Stephen Finucane
parent
d03cea1f34
commit
3c8b2a6988
@ -2,14 +2,6 @@
|
||||
#
|
||||
# openstackdocstheme documentation build configuration file
|
||||
|
||||
import openstackdocstheme
|
||||
|
||||
# Release name for PDF documents
|
||||
latex_custom_template = r"""
|
||||
\usepackage{""" + openstackdocstheme.get_pdf_theme_path() + """}
|
||||
\\newcommand{\openstacklogo}{""" + openstackdocstheme.get_openstack_logo_path() + """}
|
||||
"""
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
@ -63,23 +55,6 @@ html_static_path = ['_static/css']
|
||||
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
latex_engine = 'xelatex'
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
'papersize': 'a4paper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
'pointsize': '11pt',
|
||||
|
||||
#Default figure align
|
||||
'figure_align': 'H',
|
||||
|
||||
# Not to generate blank page after chapter
|
||||
'classoptions': ',openany',
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
'preamble': latex_custom_template,
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
|
||||
@ -32,12 +32,8 @@ Using the theme
|
||||
and then in your ``conf.py`` you can remove the import statement and
|
||||
extension listing for *oslosphinx*.
|
||||
|
||||
#. Then modify your Sphinx settings in ``conf.py`` to include::
|
||||
|
||||
html_theme = 'openstackdocs'
|
||||
|
||||
#. and to add ``'openstackdocstheme'`` to the list of extensions
|
||||
Sphinx needs to initialize::
|
||||
#. Once done, you should add ``'openstackdocstheme'`` to the list of extensions
|
||||
Sphinx needs to initialize and configure the theme::
|
||||
|
||||
extensions = [
|
||||
# ...
|
||||
@ -45,6 +41,8 @@ Using the theme
|
||||
# ...
|
||||
]
|
||||
|
||||
html_theme = 'openstackdocs'
|
||||
|
||||
#. Set the options to link to the git repository and bug tracker.
|
||||
|
||||
``repository_name``
|
||||
@ -74,72 +72,72 @@ Using the theme
|
||||
bug_project = '721'
|
||||
bug_tag = ''
|
||||
|
||||
#. Enable the "last-updated" information by setting the format for the
|
||||
timestamp::
|
||||
#. Remove the options that will be automatically configured by the theme.
|
||||
|
||||
# Must set this variable to include year, month, day, hours, and minutes.
|
||||
html_last_updated_fmt = '%Y-%m-%d %H:%M'
|
||||
- ``project``
|
||||
- ``html_last_updated_fmt``
|
||||
- ``latex_engine``
|
||||
- ``latex_elements``
|
||||
|
||||
#. If you are using this theme for API reference documentation, set the sidebar
|
||||
navigation in the `html_theme_options` in the `conf.py` file::
|
||||
In addition, if your documentation is versioned, you should remove the
|
||||
options related to versioning.
|
||||
|
||||
# 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"}
|
||||
- ``version``
|
||||
- ``release``
|
||||
|
||||
#. 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.::
|
||||
.. versionchanged:: 1.20
|
||||
|
||||
html_theme_options = {"show_other_versions": "True"}
|
||||
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.
|
||||
|
||||
#. If you are using this theme for a project with published
|
||||
documentation that predates the mitaka release cycle, set the
|
||||
``earliest_published_series`` theme option to the name of the first
|
||||
series with documentation available.::
|
||||
|
||||
html_theme_options = {
|
||||
# ...
|
||||
"earliest_published_series": "grizzly",
|
||||
# ...
|
||||
}
|
||||
Additional Configuration
|
||||
------------------------
|
||||
|
||||
.. warning::
|
||||
If you are using this theme for API reference documentation, set the sidebar
|
||||
navigation in the ``html_theme_options`` in the ``conf.py`` file::
|
||||
|
||||
Do not use this for release-notes as they are always published
|
||||
as one document with internal versioning.
|
||||
|
||||
#. To generate a PDF document using ``openstackdocstheme``, add a latex
|
||||
preamble to properly use OpenStack logo image and a font file,
|
||||
and make sure that release, title, and author information is correctly
|
||||
set in the `conf.py` file::
|
||||
|
||||
pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
|
||||
openstack_logo = openstackdocstheme.get_openstack_logo_path()
|
||||
|
||||
latex_custom_template = r"""
|
||||
\newcommand{\openstacklogo}{%s}
|
||||
\usepackage{%s}
|
||||
""" % (openstack_logo, pdf_theme_path)
|
||||
|
||||
latex_elements = {
|
||||
# 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",
|
||||
# ...
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
'preamble': latex_custom_template,
|
||||
}
|
||||
|
||||
release = '15.0.0'
|
||||
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``::
|
||||
|
||||
latex_documents = [
|
||||
('index', '[Output_filename].tex', u'[Title]',
|
||||
u'OpenStack contributors', 'manual'),
|
||||
]
|
||||
html_theme_options = {
|
||||
# ...
|
||||
"show_other_versions": "True",
|
||||
# ...
|
||||
}
|
||||
|
||||
latex_engine = 'xelatex'
|
||||
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
|
||||
@ -154,11 +152,6 @@ In the ``conf.py`` for the source documentation, add:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
extensions = [
|
||||
# ...
|
||||
'openstackdocstheme',
|
||||
]
|
||||
|
||||
openstack_projects = ['horizon']
|
||||
|
||||
Then in the documentation source, link to a target using syntax like:
|
||||
|
||||
@ -213,12 +213,28 @@ def _builder_inited(app):
|
||||
if project_name:
|
||||
app.config.project = project_name
|
||||
|
||||
app.config.html_last_updated_fmt = '%Y-%m-%d %H:%M'
|
||||
|
||||
# ...except for version/release which, if blank, should remain that way to
|
||||
# cater for unversioned documents
|
||||
if app.config.version != '':
|
||||
app.config.version = version
|
||||
app.config.release = version
|
||||
|
||||
openstack_logo = paths.get_openstack_logo_path()
|
||||
pdf_theme_path = paths.get_pdf_theme_path()
|
||||
|
||||
app.config.latex_engine = 'xelatex'
|
||||
app.config.latex_elements = {
|
||||
'papersize': 'a4paper',
|
||||
'pointsize': '11pt',
|
||||
'figure_align': 'H',
|
||||
'classoptions': ',openany',
|
||||
'preamble': r"""
|
||||
\usepackage{""" + pdf_theme_path + """}
|
||||
\\newcommand{\openstacklogo}{""" + openstack_logo + """}
|
||||
"""}
|
||||
|
||||
|
||||
def setup(app):
|
||||
logger.info('connecting events for openstackdocstheme')
|
||||
|
||||
@ -7,6 +7,9 @@ features:
|
||||
- ``project``
|
||||
- ``version``
|
||||
- ``release``
|
||||
- ``html_last_updated_fmt``
|
||||
- ``latex_engine``
|
||||
- ``latex_elements``
|
||||
|
||||
It is not necessary to retain any configuration in ``conf.py`` and, in most
|
||||
cases, such configuration will be ignored. The sole exceptions to this rule
|
||||
|
||||
Loading…
Reference in New Issue
Block a user