===========================================
 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.

#. 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::

     extensions = [
         # ...
         'openstackdocstheme',
         # ...
     ]

#. 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 = ''

#. Enable the "last-updated" information by setting the format for the
   timestamp::

     # Must set this variable to include year, month, day, hours, and minutes.
     html_last_updated_fmt = '%Y-%m-%d %H:%M'

#. 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"}


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