From 9872e6a36514e6ac196b773bf1121bbc77eb4148 Mon Sep 17 00:00:00 2001 From: Kirill Zaitsev Date: Thu, 29 Jun 2017 14:02:07 +0300 Subject: [PATCH] Use openstackdocstheme over oslosphinx This commit is part of general doc-migration effort. It replaces oslosphinx with openstackdocstheme and marks docs warnings to be treated as errors. Kuryr projects do not seem to have any docs in the openstack-manuals, so there are no docs we need to pull from that repo. However being the official project kuryr would benefit from unifying its docs with the rest of openstack projects as well as using openstackdocstheme, theme intended for official projects https://docs.openstack.org/openstackdocstheme/latest/ See https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html and https://etherpad.openstack.org/p/doc-migration-tracking for more information Change-Id: I4b854a830268beea0e463a1c75f73e8d523f3bfb --- README.rst | 2 +- doc/source/conf.py | 13 +++++++++---- releasenotes/source/conf.py | 16 ++++++++++++---- setup.cfg | 1 + test-requirements.txt | 4 ++-- 5 files changed, 25 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index 450ed13a..8f7a709b 100644 --- a/README.rst +++ b/README.rst @@ -170,7 +170,7 @@ documentation. You can install Sphinx using pip. In addition to Sphinx you will also need the following requirements (not covered by `requirements.txt`):: - $ pip install oslosphinx reno 'reno[sphinx]' + $ pip install openstackdocstheme reno 'reno[sphinx]' The source code of the documentation are under *doc*, you can generate the html files using the following command. If the generation succeeds,a diff --git a/doc/source/conf.py b/doc/source/conf.py index 111067cf..8d70342b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,9 +22,8 @@ sys.path.insert(0, os.path.abspath('../..')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.autodoc', - #'sphinx.ext.intersphinx', - 'oslosphinx', - 'reno.sphinxext' + 'openstackdocstheme', + 'reno.sphinxext', ] # autodoc generation is a bit aggressive and a nuisance when doing heavy @@ -41,6 +40,12 @@ master_doc = 'index' project = u'kuryr' copyright = u'2013, OpenStack Foundation' +# openstackdocstheme options +repository_name = 'openstack/kuryr' +bug_project = 'kuryr' +bug_tag = '' +html_last_updated_fmt = '%Y-%m-%d %H:%M' + # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True @@ -56,7 +61,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. # html_theme_path = ["."] -# html_theme = '_theme' +html_theme = 'openstackdocs' # html_static_path = ['static'] # Output file base name for HTML help builder. diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index b7028bf8..e41dd450 100644 --- a/releasenotes/source/conf.py +++ b/releasenotes/source/conf.py @@ -30,8 +30,10 @@ from kuryr.lib import version as kuryr_version # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['reno.sphinxext', - 'oslosphinx'] +extensions = [ + 'reno.sphinxext', + 'openstackdocstheme', +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -53,6 +55,12 @@ master_doc = 'index' project = u'kuryr' copyright = u'2016, Kuryr developers' +# openstackdocstheme options +repository_name = 'openstack/kuryr' +bug_project = 'kuryr' +bug_tag = '' +html_last_updated_fmt = '%Y-%m-%d %H:%M' + # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. @@ -120,7 +128,7 @@ todo_include_todos = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'default' +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 @@ -154,7 +162,7 @@ html_theme = 'default' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +# html_static_path = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/setup.cfg b/setup.cfg index 1d44f1a8..b613b336 100644 --- a/setup.cfg +++ b/setup.cfg @@ -35,6 +35,7 @@ data_files = source-dir = doc/source build-dir = doc/build all_files = 1 +warning-is-error = 1 [upload_sphinx] upload-dir = doc/build/html diff --git a/test-requirements.txt b/test-requirements.txt index 7058e333..7324f591 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -7,11 +7,11 @@ coverage>=4.0 # Apache-2.0 ddt>=1.0.1 # MIT hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0 os-testr>=0.8.0 # Apache-2.0 -oslosphinx>=4.7.0 # Apache-2.0 +openstackdocstheme>=1.11.0 # Apache-2.0 oslotest>=1.10.0 # Apache-2.0 python-subunit>=0.0.18 # Apache-2.0/BSD reno>=1.8.0 # Apache-2.0 -sphinx>=1.5.1 # BSD +sphinx>=1.6.2 # BSD testrepository>=0.0.18 # Apache-2.0/BSD testscenarios>=0.4 # Apache-2.0/BSD testtools>=1.4.0 # MIT