Browse Source

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
Kirill Zaitsev 1 year ago
parent
commit
9872e6a365
5 changed files with 25 additions and 11 deletions
  1. 1
    1
      README.rst
  2. 9
    4
      doc/source/conf.py
  3. 12
    4
      releasenotes/source/conf.py
  4. 1
    0
      setup.cfg
  5. 2
    2
      test-requirements.txt

+ 1
- 1
README.rst View File

@@ -170,7 +170,7 @@ documentation. You can install Sphinx using pip.
170 170
 In addition to Sphinx you will also need the following requirements
171 171
 (not covered by `requirements.txt`)::
172 172
 
173
-    $ pip install oslosphinx reno 'reno[sphinx]'
173
+    $ pip install openstackdocstheme reno 'reno[sphinx]'
174 174
 
175 175
 The source code of the documentation are under *doc*, you can generate the
176 176
 html files using the following command. If the generation succeeds,a

+ 9
- 4
doc/source/conf.py View File

@@ -22,9 +22,8 @@ sys.path.insert(0, os.path.abspath('../..'))
22 22
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
23 23
 extensions = [
24 24
     'sphinx.ext.autodoc',
25
-    #'sphinx.ext.intersphinx',
26
-    'oslosphinx',
27
-    'reno.sphinxext'
25
+    'openstackdocstheme',
26
+    'reno.sphinxext',
28 27
 ]
29 28
 
30 29
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -41,6 +40,12 @@ master_doc = 'index'
41 40
 project = u'kuryr'
42 41
 copyright = u'2013, OpenStack Foundation'
43 42
 
43
+# openstackdocstheme options
44
+repository_name = 'openstack/kuryr'
45
+bug_project = 'kuryr'
46
+bug_tag = ''
47
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
48
+
44 49
 # If true, '()' will be appended to :func: etc. cross-reference text.
45 50
 add_function_parentheses = True
46 51
 
@@ -56,7 +61,7 @@ pygments_style = 'sphinx'
56 61
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
57 62
 # Sphinx are currently 'default' and 'sphinxdoc'.
58 63
 # html_theme_path = ["."]
59
-# html_theme = '_theme'
64
+html_theme = 'openstackdocs'
60 65
 # html_static_path = ['static']
61 66
 
62 67
 # Output file base name for HTML help builder.

+ 12
- 4
releasenotes/source/conf.py View File

@@ -30,8 +30,10 @@ from kuryr.lib import version as kuryr_version
30 30
 # Add any Sphinx extension module names here, as strings. They can be
31 31
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32 32
 # ones.
33
-extensions = ['reno.sphinxext',
34
-              'oslosphinx']
33
+extensions = [
34
+    'reno.sphinxext',
35
+    'openstackdocstheme',
36
+]
35 37
 
36 38
 # Add any paths that contain templates here, relative to this directory.
37 39
 templates_path = ['_templates']
@@ -53,6 +55,12 @@ master_doc = 'index'
53 55
 project = u'kuryr'
54 56
 copyright = u'2016, Kuryr developers'
55 57
 
58
+# openstackdocstheme options
59
+repository_name = 'openstack/kuryr'
60
+bug_project = 'kuryr'
61
+bug_tag = ''
62
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
63
+
56 64
 # The version info for the project you're documenting, acts as replacement for
57 65
 # |version| and |release|, also used in various other places throughout the
58 66
 # built documents.
@@ -120,7 +128,7 @@ todo_include_todos = False
120 128
 # The theme to use for HTML and HTML Help pages.  See the documentation for
121 129
 # a list of builtin themes.
122 130
 #
123
-html_theme = 'default'
131
+html_theme = 'openstackdocs'
124 132
 
125 133
 # Theme options are theme-specific and customize the look and feel of a theme
126 134
 # further.  For a list of options available for each theme, see the
@@ -154,7 +162,7 @@ html_theme = 'default'
154 162
 # Add any paths that contain custom static files (such as style sheets) here,
155 163
 # relative to this directory. They are copied after the builtin static files,
156 164
 # so a file named "default.css" will overwrite the builtin "default.css".
157
-html_static_path = ['_static']
165
+# html_static_path = ['_static']
158 166
 
159 167
 # Add any extra paths that contain custom files (such as robots.txt or
160 168
 # .htaccess) here, relative to this directory. These files are copied

+ 1
- 0
setup.cfg View File

@@ -35,6 +35,7 @@ data_files =
35 35
 source-dir = doc/source
36 36
 build-dir = doc/build
37 37
 all_files = 1
38
+warning-is-error = 1
38 39
 
39 40
 [upload_sphinx]
40 41
 upload-dir = doc/build/html

+ 2
- 2
test-requirements.txt View File

@@ -7,11 +7,11 @@ coverage>=4.0 # Apache-2.0
7 7
 ddt>=1.0.1 # MIT
8 8
 hacking!=0.13.0,<0.14,>=0.12.0 # Apache-2.0
9 9
 os-testr>=0.8.0 # Apache-2.0
10
-oslosphinx>=4.7.0 # Apache-2.0
10
+openstackdocstheme>=1.11.0 # Apache-2.0
11 11
 oslotest>=1.10.0 # Apache-2.0
12 12
 python-subunit>=0.0.18 # Apache-2.0/BSD
13 13
 reno>=1.8.0 # Apache-2.0
14
-sphinx>=1.5.1 # BSD
14
+sphinx>=1.6.2 # BSD
15 15
 testrepository>=0.0.18 # Apache-2.0/BSD
16 16
 testscenarios>=0.4 # Apache-2.0/BSD
17 17
 testtools>=1.4.0 # MIT

Loading…
Cancel
Save