From b3b22ebb4e36f56787ef045ec3654fc5ff93c35f Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Mon, 5 Nov 2018 19:19:33 +0100 Subject: [PATCH] Use python3 for doc building Update requirements and code for python3, this will not work with python2 anymore. Also, update to openstackdocstheme as current OpenStack theme and configure it. Some noteworthy changes: * Remove reload, setting of UTF-8 in vmt.py - this is not needed anymore with python3. * Update requirements of Sphinx to current versions * The Markup construct does not work with python3 in conf.py, replace with simpler string. * No need to use "pip -U", remove -U option. * in vmt.py: Strings are unicode in python3, no need to check for it. Change-Id: I421e3d4a09ff19523b3bd0ca015e31a4bd1e0608 --- doc/source/_exts/vmt.py | 12 ++++++------ doc/source/conf.py | 31 +++++++++++-------------------- test-requirements.txt | 4 ++-- tox.ini | 5 ++--- 4 files changed, 21 insertions(+), 31 deletions(-) diff --git a/doc/source/_exts/vmt.py b/doc/source/_exts/vmt.py index f03a53c..9581a6e 100644 --- a/doc/source/_exts/vmt.py +++ b/doc/source/_exts/vmt.py @@ -1,15 +1,15 @@ #!/usr/bin/env python import glob import os -import sys import textwrap from jinja2 import FileSystemLoader from jinja2.environment import Environment import yaml -reload(sys) -sys.setdefaultencoding("utf-8") +from sphinx.util import logging + +LOG = logging.getLogger(__name__) def to_snake_case(d): @@ -23,7 +23,7 @@ def to_snake_case(d): def to_paragraphs(d, *args): for k in args: - if k in d and (isinstance(d[k], str) or isinstance(d[k], unicode)): + if k in d and isinstance(d[k], str): d[k] = '\n'.join(textwrap.wrap(d[k])) @@ -57,7 +57,7 @@ def render_template(template, data, **kwargs): def render(source, template, **kwargs): - vals = yaml.safe_load(open(source).read().decode('utf-8')) + vals = yaml.safe_load(open(source).read()) to_snake_case(vals) to_paragraphs(vals, 'description', 'errata') return render_template(template, vals, **kwargs) @@ -87,6 +87,6 @@ def reverse_toctree(app, doctree, docname): def setup(app): - app.info('Loading the vmt extension') + LOG.info('Loading the vmt extension') app.connect('builder-inited', build_advisories) app.connect("doctree-resolved", reverse_toctree) diff --git a/doc/source/conf.py b/doc/source/conf.py index f478c5d..a059501 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -12,12 +12,9 @@ # serve to show the default. import datetime -import subprocess import sys import os -from jinja2.utils import Markup - # 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. @@ -32,7 +29,7 @@ sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts')) # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'vmt', - 'oslosphinx' + 'openstackdocstheme' ] todo_include_todos = True @@ -46,18 +43,17 @@ source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8-sig' +# Setting for openstackdocstheme: +repository_name = "openstack/ossa" +bug_project = 'ossa' + # The master toctree document. master_doc = 'index' # General information about the project. project = u'OpenStack Security Advisories' -copyright = Markup(u'%s, OpenStack Vulnerability Management Team. ' - u'Freely licensed under CC BY ' - u'3.0. Propose changes to the ' - u'ossa git repo' - % datetime.date.today().year) +copyright = ('%d, OpenStack Vulnerabiltity Management Team' % + datetime.date.today().year) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -98,12 +94,14 @@ modindex_common_prefix = [] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'nature' +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 # documentation. -#html_theme_options = {} +html_theme_options = { + 'display_global_toc_section': False, +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] @@ -129,13 +127,6 @@ html_theme = 'nature' # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -# 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 = subprocess.Popen( - git_cmd, stdout=subprocess.PIPE).communicate()[0] - # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True diff --git a/test-requirements.txt b/test-requirements.txt index 9d515c0..9f84d56 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -1,5 +1,5 @@ # needed for doc build Jinja2>=2.7.3 PyYAML==3.11 -sphinx>=1.1.2,!=1.2.0,<1.3 -oslosphinx>=2.2.0 # Apache-2.0 +sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD +openstackdocstheme>=1.19.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index 3800903..c6ade09 100644 --- a/tox.ini +++ b/tox.ini @@ -5,12 +5,11 @@ skipsdist = True [testenv] usedevelop = True -install_command = pip install -U {opts} {packages} +install_command = pip install {opts} {packages} setenv = VIRTUAL_ENV={envdir} [testenv:docs] -# The repo does not work with python3 yet, so no basepypthon set -# to python3. +basepython = python3 deps = -r{toxinidir}/test-requirements.txt commands = sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html