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

@@ -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,

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::
+#. Once done, you should add ``'openstackdocstheme'`` to the list of extensions
-
+   Sphinx needs to initialize and configure the theme::
-     html_theme = 'openstackdocs'
-
-#. and to add ``'openstackdocstheme'`` to the list of extensions
-   Sphinx needs to initialize::
 
      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,33 +72,61 @@ Using the theme
       bug_project = '721'
       bug_tag = ''
 
-#. Enable the "last-updated" information by setting the format for the
+#. Remove the options that will be automatically configured by the theme.
-   timestamp::
 
-     # Must set this variable to include year, month, day, hours, and minutes.
+   - ``project``
-     html_last_updated_fmt = '%Y-%m-%d %H:%M'
+   - ``html_last_updated_fmt``
+   - ``latex_engine``
+   - ``latex_elements``
 
-#. If you are using this theme for API reference documentation, set the sidebar
+   In addition, if your documentation is versioned, you should remove the
-   navigation in the `html_theme_options` in the `conf.py` file::
+   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",
+    html_theme_options = {
-                           "sidebar_mode": "toc"}
+        # ...
+        "sidebar_dropdown": "api_ref",
+        "sidebar_mode": "toc",
+        # ...
+    }
 
-#. If you are using this theme for documentation you want to release based on
+If you are using this theme for documentation you want to release based on git
-   git tags on your repository, set the release dropdown menu option in the
+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`` in the ``conf.py`` file. By default it is set to
+``False``::
 
-    html_theme_options = {"show_other_versions": "True"}
+    html_theme_options = {
+        # ...
+        "show_other_versions": "True",
+        # ...
+    }
 
-#. If you are using this theme for a project with published
+If you are using this theme for a project with published documentation that
-   documentation that predates the mitaka release cycle, set the
+predates the Mitaka release cycle, set the earliest published version in the
-   ``earliest_published_series`` theme option to the name of the first
+``html_theme_options`` in the ``conf.py`` file to the name of the first series
-   series with documentation available.::
+with documentation available. By default it is set to ``None``::
 
     html_theme_options = {
         # ...
@@ -110,36 +136,8 @@ Using the theme
 
 .. warning::
 
-      Do not use this for release-notes as they are always published
+    Do not use this for release-notes as they are always published as one
-      as one document with internal versioning.
+    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 = {
-        # ...
-        # Additional stuff for the LaTeX preamble.
-        'preamble': latex_custom_template,
-    }
-
-    release = '15.0.0'
-
-    latex_documents = [
-    ('index', '[Output_filename].tex', u'[Title]',
-     u'OpenStack contributors', 'manual'),
-    ]
-
-    latex_engine = 'xelatex'
 
 
 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:

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')

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