Developer Reference: Adopt the openstackdocstheme

To allow for our developer reference to be consistent with
the rest of the openstack documentation, we need to import
and render this theme on our developer reference.

This gives users a consistent experience as they may
be acquainted with the rest of the OpenStack documentation
(Admin Guide, User Guide, API Guide etc.)
before perusing the Manila developer reference.

It also provides our devref the "log-a-bug" feature so
readers may bring any mis-information to our attention.

This patch is part of a series of commits to improve
in-tree documentation.

Change-Id: I0e4686a273c5bf45c1d57764cd4c312870b06d6e
Partially-implements: bp improve-manila-developer-docs
This commit is contained in:
Goutham Pacha Ravi
2016-05-04 21:10:09 -04:00
parent c44d2f17c8
commit 8de817d16e
2 changed files with 35 additions and 10 deletions

View File

@@ -17,6 +17,8 @@ import sys
import os import os
import warnings import warnings
import openstackdocstheme
# If extensions (or modules to document with autodoc) are in another directory, # If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the # add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here. # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -67,7 +69,7 @@ master_doc = 'index'
# General information about the project. # General information about the project.
project = u'manila' project = u'manila'
copyright = u'2010-present, OpenStack, LLC' copyright = u'2010-present, Manila contributors'
# The version info for the project you're documenting, acts as replacement for # The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the # |version| and |release|, also used in various other places throughout the
@@ -79,6 +81,28 @@ release = version_info.release_string()
# The short X.Y version. # The short X.Y version.
version = version_info.version_string() version = version_info.version_string()
# A few variables have to be set for the log-a-bug feature.
# giturl: The location of conf.py on Git. Must be set manually.
# gitsha: The SHA checksum of the bug description. Automatically extracted
# from git log.
# bug_tag: Tag for categorizing the bug. Must be set manually.
# These variables are passed to the logabug code via html_context.
giturl = u'http://git.openstack.org/cgit/openstack/manila/tree/doc/source'
git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '"
gitsha = os.popen(git_cmd).read().strip('\n')
bug_tag = u'docs'
# source tree
pwd = os.getcwd()
html_context = {
"pwd": pwd,
"gitsha": gitsha,
"bug_tag": bug_tag,
"giturl": giturl,
"bug_project": "manila",
}
# The language for content autogenerated by Sphinx. Refer to documentation # The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages. # for a list of supported languages.
#language = None #language = None
@@ -132,19 +156,19 @@ man_pages = [
# -- Options for HTML output -------------------------------------------------- # -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with # The theme to use for HTML and HTML Help pages. See the documentation for
# Sphinx are currently 'default' and 'sphinxdoc'. # a list of builtin themes.
# html_theme_path = ["."] html_theme = 'openstackdocs'
# html_theme = '_theme'
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [openstackdocstheme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme # Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the # further. For a list of options available for each theme, see the
# documentation. # documentation.
html_theme_options = {} html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to # The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation". # "<project> v<release> documentation".
#html_title = None #html_title = None
@@ -226,8 +250,8 @@ htmlhelp_basename = 'maniladoc'
# (source start file, target name, title, author, documentclass # (source start file, target name, title, author, documentclass
# [howto/manual]). # [howto/manual]).
latex_documents = [ latex_documents = [
('index', 'Manila.tex', u'Manila Documentation', ('index', 'Manila.tex', u'Manila Developer Documentation',
u'Anso Labs, LLC', 'manual'), u'Manila contributors', 'manual'),
] ]
# The name of an image file (relative to this directory) to place at the top of # The name of an image file (relative to this directory) to place at the top of

View File

@@ -13,6 +13,7 @@ mock>=1.2 # BSD
iso8601>=0.1.11 # MIT iso8601>=0.1.11 # MIT
oslotest>=1.10.0 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0
oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0 oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0
openstackdocstheme>=1.0.3 # Apache-2.0
# Do not remove 'PyMySQL' and 'psycopg2' dependencies. They are used # Do not remove 'PyMySQL' and 'psycopg2' dependencies. They are used
# by oslo_db lib for running MySQL and PostgreSQL DB migration tests. # by oslo_db lib for running MySQL and PostgreSQL DB migration tests.