From 2a1b0b05234048fe0f29df459b984b87faea7505 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Fri, 16 Jun 2017 04:08:37 +0900 Subject: [PATCH] docs: switch to openstackdocstheme The docs reorganization proposed in the docs-specs [1], we will migrate our sphinx theme to openstackdocsthems. This commit switches our docs theme to it, Also ajust title levels. openstackdocstheme assume one title (first level) per page. Second or later first-level titles are not shown. This changes title levels to match openstackdocsthem requirements. Note that oslosphinx is used by releasenotes build, so it is not dropped from test-requirements.txt. [1] https://review.openstack.org/#/c/472275/ Change-Id: I72d55c26401ae9bfd06626d1b1584a368bbd9f86 --- doc/source/conf.py | 19 +++++++++++++++---- doc/source/dashboards/index.rst | 7 +++++-- doc/source/index.rst | 12 ++++++------ test-requirements.txt | 1 + 4 files changed, 27 insertions(+), 12 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 52b645dbf6f..c3c7d0d4eed 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -31,6 +31,8 @@ import subprocess import sys import warnings +import openstackdocstheme + # 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 # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -48,7 +50,6 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.ifconfig', 'sphinx.ext.graphviz', 'sphinx.ext.todo', - 'oslosphinx', 'support_matrix'] todo_include_todos = True @@ -126,6 +127,7 @@ modindex_common_prefix = ['neutron.'] # Sphinx are currently 'default' and 'sphinxdoc'. # html_theme_path = ["."] # html_theme = '_theme' +html_theme = 'openstackdocs' # 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 @@ -134,6 +136,7 @@ modindex_common_prefix = ['neutron.'] # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = ['_theme'] +html_theme_path = [openstackdocstheme.get_html_theme_path()] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -159,14 +162,22 @@ html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. #html_last_updated_fmt = '%b %d, %Y' -git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local -", - "n1"] +git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1" try: - html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8') + html_last_updated_fmt = os.popen(git_cmd).read() except Exception: warnings.warn('Cannot get last updated time from git repository. ' 'Not setting "html_last_updated_fmt".') +gitsha = os.popen("/usr/bin/git rev-parse HEAD").read() +giturl = u'https://git.openstack.org/cgit/openstack/neutron/tree/doc/source' +# html_context allows us to pass arbitrary values into the html template +html_context = { + "gitsha": gitsha, + "giturl": giturl, + "bug_project": "neutron", + "bug_tag": "doc", + } # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. diff --git a/doc/source/dashboards/index.rst b/doc/source/dashboards/index.rst index 1202a033ca0..a3bc33f7c16 100644 --- a/doc/source/dashboards/index.rst +++ b/doc/source/dashboards/index.rst @@ -1,5 +1,8 @@ +CI Status Dashboards +==================== + Gerrit Dashboards -================= +----------------- - `Neutron master branch reviews `_ - `Neutron subproject reviews (master branch) `_ @@ -12,7 +15,7 @@ Useful dashboard definitions are found in ``dashboards`` directory. .. _Gerrit Dashboard Creator: https://github.com/openstack/gerrit-dash-creator Grafana Dashboards -================== +------------------ Look for neutron and networking-* dashboard by names by going to the following link: diff --git a/doc/source/index.rst b/doc/source/index.rst index 0a243853da0..f5805c64c94 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -40,7 +40,7 @@ The `Neutron Development wiki`_ is also a good resource for new contributors. Enjoy! Neutron Policies -================ +---------------- .. toctree:: :maxdepth: 2 @@ -48,7 +48,7 @@ Neutron Policies policies/index Neutron Stadium -=============== +---------------- .. toctree:: :maxdepth: 2 @@ -56,7 +56,7 @@ Neutron Stadium stadium/index Neutron Feature Classification -============================== +------------------------------ .. toctree:: :maxdepth: 3 @@ -64,7 +64,7 @@ Neutron Feature Classification feature_classification/index Developer Docs -============== +-------------- .. toctree:: :maxdepth: 3 @@ -72,7 +72,7 @@ Developer Docs devref/index Dashboards -========== +---------- There is a collection of dashboards to help developers and reviewers located here. @@ -83,6 +83,6 @@ located here. dashboards/index API Extensions -============== +-------------- Go to http://api.openstack.org for information about OpenStack Network API extensions. diff --git a/test-requirements.txt b/test-requirements.txt index f9c92cc96f6..1419ab9a962 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -8,6 +8,7 @@ fixtures>=3.0.0 # Apache-2.0/BSD mock>=2.0 # BSD python-subunit>=0.0.18 # Apache-2.0/BSD sphinx!=1.6.1,>=1.5.1 # BSD +openstackdocstheme>=1.5.0 # Apache-2.0 oslosphinx>=4.7.0 # Apache-2.0 testrepository>=0.0.18 # Apache-2.0/BSD testtools>=1.4.0 # MIT