Doug Hellmann 2f8d5756fb add more clear guidelines for when using oslosphinx is appropriate

Based on the branding guidelines linked in this patch, projects that are
not officially under governance should not use the theme in most
circumstances.

Change-Id: Id6ded25a20965803ddbca0c2e587d3f4c476168f
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

2017-02-15 11:58:32 -05:00

1.6 KiB

Raw Blame History

Using the oslosphinx Theme

Guidelines

Prior to using this theme, ensure your project can use the OpenStack brand by referring to the brand guidelines at http://www.openstack.org/brand. In particular, if the project is not under OpenStack governance as an "official" project, it should not use this theme.

If your documentation is not being published to an openstack.org site, that may be a signal that you should not use this theme.

Sphinx Configuration

To use the theme, add 'oslosphinx' to the extensions list in the conf.py file in your Sphinx project.

Incubating Projects

If you are an incubating project, set:

html_theme_options = {'incubating': True}

in your conf.py as well, to enable the Incubation theme.

Linking to a Source Repository

oslosphinx defines a configuration option oslosphinx_cgit_link which should be the URL to the git repository browser for the project being documented. The default is a guess, and will be right for a lot of projects, but to ensure that it is correct in all situations it is best to set the value in conf.py:

oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/oslosphinx'

Showing Older Versions of Documentation

oslosphinx can automatically add links for previous versions of your project's documentation to the sidebar. If this feature is enabled links will be generated for each git tag. To enable this behavior, set:

html_theme_options = {'show_other_versions': True}

in your conf.py.

1.6 KiB Raw Blame History