Browse Source

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
Andreas Jaeger 5 months ago
parent
commit
b3b22ebb4e
4 changed files with 21 additions and 31 deletions
  1. 6
    6
      doc/source/_exts/vmt.py
  2. 11
    20
      doc/source/conf.py
  3. 2
    2
      test-requirements.txt
  4. 2
    3
      tox.ini

+ 6
- 6
doc/source/_exts/vmt.py View File

@@ -1,15 +1,15 @@
1 1
 #!/usr/bin/env python
2 2
 import glob
3 3
 import os
4
-import sys
5 4
 import textwrap
6 5
 
7 6
 from jinja2 import FileSystemLoader
8 7
 from jinja2.environment import Environment
9 8
 import yaml
10 9
 
11
-reload(sys)
12
-sys.setdefaultencoding("utf-8")
10
+from sphinx.util import logging
11
+
12
+LOG = logging.getLogger(__name__)
13 13
 
14 14
 
15 15
 def to_snake_case(d):
@@ -23,7 +23,7 @@ def to_snake_case(d):
23 23
 
24 24
 def to_paragraphs(d, *args):
25 25
     for k in args:
26
-        if k in d and (isinstance(d[k], str) or isinstance(d[k], unicode)):
26
+        if k in d and isinstance(d[k], str):
27 27
             d[k] = '\n'.join(textwrap.wrap(d[k]))
28 28
 
29 29
 
@@ -57,7 +57,7 @@ def render_template(template, data, **kwargs):
57 57
 
58 58
 
59 59
 def render(source, template, **kwargs):
60
-    vals = yaml.safe_load(open(source).read().decode('utf-8'))
60
+    vals = yaml.safe_load(open(source).read())
61 61
     to_snake_case(vals)
62 62
     to_paragraphs(vals, 'description', 'errata')
63 63
     return render_template(template, vals, **kwargs)
@@ -87,6 +87,6 @@ def reverse_toctree(app, doctree, docname):
87 87
 
88 88
 
89 89
 def setup(app):
90
-    app.info('Loading the vmt extension')
90
+    LOG.info('Loading the vmt extension')
91 91
     app.connect('builder-inited', build_advisories)
92 92
     app.connect("doctree-resolved", reverse_toctree)

+ 11
- 20
doc/source/conf.py View File

@@ -12,12 +12,9 @@
12 12
 # serve to show the default.
13 13
 
14 14
 import datetime
15
-import subprocess
16 15
 import sys
17 16
 import os
18 17
 
19
-from jinja2.utils import Markup
20
-
21 18
 # If extensions (or modules to document with autodoc) are in another directory,
22 19
 # add these directories to sys.path here. If the directory is relative to the
23 20
 # 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'))
32 29
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
33 30
 extensions = [
34 31
     'vmt',
35
-    'oslosphinx'
32
+    'openstackdocstheme'
36 33
 ]
37 34
 
38 35
 todo_include_todos = True
@@ -46,18 +43,17 @@ source_suffix = '.rst'
46 43
 # The encoding of source files.
47 44
 #source_encoding = 'utf-8-sig'
48 45
 
46
+# Setting for openstackdocstheme:
47
+repository_name = "openstack/ossa"
48
+bug_project = 'ossa'
49
+
49 50
 # The master toctree document.
50 51
 master_doc = 'index'
51 52
 
52 53
 # General information about the project.
53 54
 project = u'OpenStack Security Advisories'
54
-copyright = Markup(u'%s, OpenStack Vulnerability Management Team. '
55
-                   u'Freely licensed under <a href="http://'
56
-                   u'creativecommons.org/licenses/by/3.0/legalcode">CC BY '
57
-                   u'3.0</a>. Propose changes to the <a '
58
-                   u'href="https://git.openstack.org/cgit/openstack/ossa">'
59
-                   u'ossa git repo</a>'
60
-                   % datetime.date.today().year)
55
+copyright = ('%d, OpenStack Vulnerabiltity Management Team' %
56
+             datetime.date.today().year)
61 57
 
62 58
 # The language for content autogenerated by Sphinx. Refer to documentation
63 59
 # for a list of supported languages.
@@ -98,12 +94,14 @@ modindex_common_prefix = []
98 94
 
99 95
 # The theme to use for HTML and HTML Help pages.  See the documentation for
100 96
 # a list of builtin themes.
101
-html_theme = 'nature'
97
+html_theme = 'openstackdocs'
102 98
 
103 99
 # Theme options are theme-specific and customize the look and feel of a theme
104 100
 # further.  For a list of options available for each theme, see the
105 101
 # documentation.
106
-#html_theme_options = {}
102
+html_theme_options = {
103
+    'display_global_toc_section': False,
104
+}
107 105
 
108 106
 # Add any paths that contain custom themes here, relative to this directory.
109 107
 #html_theme_path = []
@@ -129,13 +127,6 @@ html_theme = 'nature'
129 127
 # so a file named "default.css" will overwrite the builtin "default.css".
130 128
 html_static_path = ['_static']
131 129
 
132
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
133
-# using the given strftime format.
134
-git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
135
-    "-n1"]
136
-html_last_updated_fmt = subprocess.Popen(
137
-    git_cmd, stdout=subprocess.PIPE).communicate()[0]
138
-
139 130
 # If true, SmartyPants will be used to convert quotes and dashes to
140 131
 # typographically correct entities.
141 132
 #html_use_smartypants = True

+ 2
- 2
test-requirements.txt View File

@@ -1,5 +1,5 @@
1 1
 # needed for doc build
2 2
 Jinja2>=2.7.3
3 3
 PyYAML==3.11
4
-sphinx>=1.1.2,!=1.2.0,<1.3
5
-oslosphinx>=2.2.0  # Apache-2.0
4
+sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
5
+openstackdocstheme>=1.19.0 # Apache-2.0

+ 2
- 3
tox.ini View File

@@ -5,12 +5,11 @@ skipsdist = True
5 5
 
6 6
 [testenv]
7 7
 usedevelop = True
8
-install_command = pip install -U {opts} {packages}
8
+install_command = pip install {opts} {packages}
9 9
 setenv = VIRTUAL_ENV={envdir}
10 10
 
11 11
 [testenv:docs]
12
-# The repo does not work with python3 yet, so no basepypthon set
13
-# to python3.
12
+basepython = python3
14 13
 deps = -r{toxinidir}/test-requirements.txt
15 14
 commands = sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
16 15
 

Loading…
Cancel
Save