From 3c8b2a698864afea55bf2247d6c50baadaf4fb72 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 15 Feb 2018 17:15:40 +0000 Subject: [PATCH] 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 --- doc/source/conf.py | 25 ---- doc/source/index.rst | 119 +++++++++--------- openstackdocstheme/ext.py | 16 +++ ...toconfigure-settings-7083fdeeb121da89.yaml | 3 + 4 files changed, 75 insertions(+), 88 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index cffb26b..aecb5b3 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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, diff --git a/doc/source/index.rst b/doc/source/index.rst index 0c7791f..faea9c8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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: diff --git a/openstackdocstheme/ext.py b/openstackdocstheme/ext.py index 1b0d62a..f549e43 100644 --- a/openstackdocstheme/ext.py +++ b/openstackdocstheme/ext.py @@ -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') diff --git a/releasenotes/notes/autoconfigure-settings-7083fdeeb121da89.yaml b/releasenotes/notes/autoconfigure-settings-7083fdeeb121da89.yaml index 3310c00..5bbd555 100644 --- a/releasenotes/notes/autoconfigure-settings-7083fdeeb121da89.yaml +++ b/releasenotes/notes/autoconfigure-settings-7083fdeeb121da89.yaml @@ -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