From 32cf20135bbc9c3e3df0da21a12a4f79404c73a0 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 29 Mar 2019 11:58:34 +0000 Subject: [PATCH] docs: Resolve issues with Sphinx 2.0 There are multiple steps necessary here: - Switch to openstackdocstheme which, unlike the EOL'd oslosphinx theme, supports Sphinx 2.0. This is mostly trivial, though we do need to set the 'release' and 'version' options to the empty string since specs, like release notes and API docs, are unversioned. - Require yasfb 0.8.0, which adds support for Sphinx 2.0 - Remove configuration for configuration for the 'autodoc' extension, any builder that isn't HTML or LaTeX, or stuff that duplicates defaults. All of these were noise that was simply confusing matters. Change-Id: I111f5e2b0314b35bdde3e00f7615a380734bc2aa --- doc/requirements.txt | 4 +-- doc/source/conf.py | 60 +++++++++++++++++------------------------- doc/source/redirect.py | 20 +++++++------- 3 files changed, 35 insertions(+), 49 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 6cd98bc77..df17b80b2 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,7 +1,7 @@ # The order of packages is significant, because pip processes them in the order # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. -oslosphinx>=4.7.0 # Apache-2.0 sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD sphinxcontrib-seqdiag>=0.8.4 # BSD -yasfb>=0.5.1,!=0.6.0 +openstackdocstheme>=1.19.0 # Apache-2.0 +yasfb>=0.8.0 # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py index fd561c173..40a9e761d 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -9,27 +9,20 @@ import os # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('.')) -# -- General configuration ----------------------------------------------------- +# -- General configuration ---------------------------------------------------- -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['redirect', - 'sphinx.ext.autodoc', - 'sphinx.ext.todo', - 'sphinx.ext.viewcode', - 'oslosphinx', - 'yasfb', - 'sphinxcontrib.seqdiag', - ] +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'redirect', + 'sphinx.ext.todo', + 'openstackdocstheme', + 'yasfb', + 'sphinxcontrib.seqdiag', +] todo_include_todos = True -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - # The master toctree document. master_doc = 'index' @@ -37,30 +30,20 @@ master_doc = 'index' project = u'Nova Specs' copyright = u'%s, OpenStack Nova Team' % datetime.date.today().year -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -add_module_names = False - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -show_authors = False - # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. modindex_common_prefix = ['nova-specs.'] -# -- Options for HTML output --------------------------------------------------- +version = '' +release = '' + +# -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'nature' - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1" -html_last_updated_fmt = os.popen(git_cmd).read() +html_theme = 'openstackdocs' # If false, no module index is generated. html_domain_indices = False @@ -68,15 +51,20 @@ html_domain_indices = False # If false, no index is generated. html_use_index = False -# Output file base name for HTML help builder. -htmlhelp_basename = 'Nova-Specsdoc' + +# -- openstackdocstheme configuration ----------------------------------------- + +repository_name = 'openstack/nova-specs' +use_storyboard = False -# -- yasfb configuration ------------------------------------------------------- +# -- yasfb configuration ------------------------------------------------------ feed_base_url = 'http://specs.openstack.org/openstack/nova-specs' feed_author = 'OpenStack Nova Team' -# -- seqdiag configuration ----------------------------------------------------- + +# -- seqdiag configuration ---------------------------------------------------- + seqdiag_html_image_format = 'SVG' seqdiag_antialias = True diff --git a/doc/source/redirect.py b/doc/source/redirect.py index 099159f28..c3a7ad25f 100644 --- a/doc/source/redirect.py +++ b/doc/source/redirect.py @@ -5,15 +5,9 @@ import os.path -from sphinx.application import ENV_PICKLE_FILENAME -from sphinx.util.console import bold +from sphinx.util import logging - -def setup(app): - from sphinx.application import Sphinx - if not isinstance(app, Sphinx): - return - app.connect('build-finished', emit_redirects) +LOG = logging.getLogger(__name__) def process_redirect_file(app, path, ent): @@ -35,7 +29,7 @@ def process_redirect_file(app, path, ent): def emit_redirects(app, exc): - app.builder.info(bold('scanning %s for redirects...') % app.builder.srcdir) + LOG.info('scanning %s for redirects...', app.builder.srcdir) def process_directory(path): for ent in os.listdir(path): @@ -43,8 +37,12 @@ def emit_redirects(app, exc): if os.path.isdir(p): process_directory(p) elif ent == 'redirects': - app.builder.info(' found redirects at %s' % p) + LOG.info(' found redirects at %s' % p) process_redirect_file(app, path, ent) process_directory(app.builder.srcdir) - app.builder.info('...done') + LOG.info('...done') + + +def setup(app): + app.connect('build-finished', emit_redirects)