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,72 +72,72 @@ 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.
 
-     # To use the API Reference sidebar dropdown menu,
+   - ``version``
-     # uncomment the html_theme_options parameter.  The theme
+   - ``release``
-     # 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
+.. versionchanged:: 1.20
-   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"}
+   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 = {
+Additional Configuration
-         # ...
+------------------------
-         "earliest_published_series": "grizzly",
-         # ...
-     }
 
-   .. 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
+    # To use the API Reference sidebar dropdown menu,
-      as one document with internal versioning.
+    # uncomment the html_theme_options parameter.  The theme
-
+    # variable, sidebar_dropdown, should be set to `api_ref`.
-#. To generate a PDF document using ``openstackdocstheme``, add a latex
+    # Otherwise, the list of links for the User and Ops docs
-   preamble to properly use OpenStack logo image and a font file,
+    # appear in the sidebar dropdown menu.
-   and make sure that release, title, and author information is correctly
+    html_theme_options = {
-   set in the `conf.py` file::
+        # ...
-
+        "sidebar_dropdown": "api_ref",
-    pdf_theme_path = openstackdocstheme.get_pdf_theme_path()
+        "sidebar_mode": "toc",
-    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'
+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 = [
+    html_theme_options = {
-    ('index', '[Output_filename].tex', u'[Title]',
+        # ...
-     u'OpenStack contributors', 'manual'),
+        "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:

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