Browse Source

Update docs building

Use sphinx-build and cleanup unused config.
Switch to openstackdocstheme 1.20.0 and remove obsolete settings from
conf.py files.

Update some RST files, they had wrong indentation.

Change-Id: Iaad2841db809f8a343fb8b1031cf8d0587d70442
tags/2.0.0
Andreas Jaeger 1 month ago
parent
commit
06d7ac27b7

+ 1
- 1
doc/source/conf.py View File

66
 # So that we can enable "log-a-bug" links from each output HTML page, this
66
 # So that we can enable "log-a-bug" links from each output HTML page, this
67
 # variable must be set to a format that includes year, month, day, hours and
67
 # variable must be set to a format that includes year, month, day, hours and
68
 # minutes.
68
 # minutes.
69
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
69
+# html_last_updated_fmt = '%Y-%m-%d %H:%M'
70
 
70
 
71
 # Output file base name for HTML help builder.
71
 # Output file base name for HTML help builder.
72
 htmlhelp_basename = '%sdoc' % project
72
 htmlhelp_basename = '%sdoc' % project

+ 5
- 5
doc/source/installation.rst View File

4
 
4
 
5
 At the command line:
5
 At the command line:
6
 
6
 
7
-   .. code-block:: console
7
+.. code-block:: console
8
 
8
 
9
-      $ pip install openstack-doc-tools
9
+   $ pip install openstack-doc-tools
10
 
10
 
11
 Or, if you have virtualenvwrapper installed:
11
 Or, if you have virtualenvwrapper installed:
12
 
12
 
13
-   .. code-block:: console
13
+.. code-block:: console
14
 
14
 
15
-      $ mkvirtualenv openstack-doc-tools
16
-      $ pip install openstack-doc-tools
15
+   $ mkvirtualenv openstack-doc-tools
16
+   $ pip install openstack-doc-tools

+ 52
- 52
doc/source/man/openstack-doc-test.rst View File

2
 openstack-doc-test
2
 openstack-doc-test
3
 ==================
3
 ==================
4
 
4
 
5
-------------------------------------------------------
5
+-------------------------
6
 OpenStack Validation tool
6
 OpenStack Validation tool
7
-------------------------------------------------------
7
+-------------------------
8
 
8
 
9
 SYNOPSIS
9
 SYNOPSIS
10
 ========
10
 ========
20
 OPTIONS
20
 OPTIONS
21
 =======
21
 =======
22
 
22
 
23
-  **General options**
23
+**General options**
24
 
24
 
25
-  **--api-site**
26
-       Special handling for api-site and other API repositories
27
-       to handle WADL.
25
+**--api-site**
26
+     Special handling for api-site and other API repositories
27
+     to handle WADL.
28
 
28
 
29
-  **--build-file-exception BUILD_FILE_EXCEPTION**
30
-      File that will be skipped during delete and build checks to
31
-      generate dependencies. This should be done for invalid XML files
32
-      only.
29
+**--build-file-exception BUILD_FILE_EXCEPTION**
30
+    File that will be skipped during delete and build checks to
31
+    generate dependencies. This should be done for invalid XML files
32
+    only.
33
 
33
 
34
-  **--check-build**
35
-        Try to build books using modified files.
34
+**--check-build**
35
+      Try to build books using modified files.
36
 
36
 
37
-  **--check-deletions**
38
-       Check that deleted files are not used.
37
+**--check-deletions**
38
+     Check that deleted files are not used.
39
 
39
 
40
-  **--check-links**
41
-       Check that linked URLs are valid and reachable.
40
+**--check-links**
41
+     Check that linked URLs are valid and reachable.
42
 
42
 
43
-  **--check-niceness**
44
-       Check the niceness of files, for example whitespace.
43
+**--check-niceness**
44
+     Check the niceness of files, for example whitespace.
45
 
45
 
46
-  **--check-syntax**
47
-        Check the syntax of modified files.
46
+**--check-syntax**
47
+      Check the syntax of modified files.
48
 
48
 
49
-  **--check-all**
50
-       Run all checks (default if no arguments are given).
49
+**--check-all**
50
+     Run all checks (default if no arguments are given).
51
 
51
 
52
-  **--config-file PATH**
53
-       Path to a config file to use. Multiple config files can be
54
-       specified, with values in later files taking precedence.
52
+**--config-file PATH**
53
+     Path to a config file to use. Multiple config files can be
54
+     specified, with values in later files taking precedence.
55
 
55
 
56
-  **--debug**
57
-      Enable debug code.
56
+**--debug**
57
+    Enable debug code.
58
 
58
 
59
-  **--file-exception FILE_EXCEPTION**
60
-      File that will be skipped during niceness and syntax validation.
59
+**--file-exception FILE_EXCEPTION**
60
+    File that will be skipped during niceness and syntax validation.
61
 
61
 
62
-  **--force**
63
-      Force the validation of all files and build all books.
62
+**--force**
63
+    Force the validation of all files and build all books.
64
 
64
 
65
-  **-h, --help**
66
-      Show help message and exit.
65
+**-h, --help**
66
+    Show help message and exit.
67
 
67
 
68
-  **--ignore-dir IGNORE_DIR**
69
-      Directory to ignore for building of manuals. The parameter can
70
-      be passed multiple times to add several directories.
68
+**--ignore-dir IGNORE_DIR**
69
+    Directory to ignore for building of manuals. The parameter can
70
+    be passed multiple times to add several directories.
71
 
71
 
72
-  **--language LANGUAGE, -l LANGUAGE**
73
-      Build translated manual for language in path generate/$LANGUAGE .
72
+**--language LANGUAGE, -l LANGUAGE**
73
+    Build translated manual for language in path generate/$LANGUAGE .
74
 
74
 
75
-  **--only-book ONLY_BOOK**
76
-      Build each specified manual.
75
+**--only-book ONLY_BOOK**
76
+    Build each specified manual.
77
 
77
 
78
-  **--parallel**
79
-      Build books in parallel (default).
78
+**--parallel**
79
+    Build books in parallel (default).
80
 
80
 
81
-  **--print-unused-files**
82
-      Print list of files that are not included anywhere as part of
83
-      check-build.
81
+**--print-unused-files**
82
+    Print list of files that are not included anywhere as part of
83
+    check-build.
84
 
84
 
85
-  **--publish**
86
-      Setup content in publish-docs directory for publishing to
87
-      external website.
85
+**--publish**
86
+    Setup content in publish-docs directory for publishing to
87
+    external website.
88
 
88
 
89
-  **--verbose**
90
-       Verbose execution.
89
+**--verbose**
90
+     Verbose execution.
91
 
91
 
92
-  **--version**
93
-       Output version number.
92
+**--version**
93
+     Output version number.
94
 
94
 
95
 FILES
95
 FILES
96
 =====
96
 =====

+ 2
- 2
doc/source/usage.rst View File

4
 
4
 
5
 To use openstack-doc-tools in a project:
5
 To use openstack-doc-tools in a project:
6
 
6
 
7
-   .. code-block:: python
7
+.. code-block:: python
8
 
8
 
9
-      import os_doc_tools
9
+   import os_doc_tools

+ 1
- 1
lower-constraints.txt View File

21
 MarkupSafe==1.0
21
 MarkupSafe==1.0
22
 mccabe==0.2.1
22
 mccabe==0.2.1
23
 mock==2.0.0
23
 mock==2.0.0
24
-openstackdocstheme==1.18.1
24
+openstackdocstheme==1.20.0
25
 pbr==2.0.0
25
 pbr==2.0.0
26
 pep8==1.5.7
26
 pep8==1.5.7
27
 pyflakes==0.8.1
27
 pyflakes==0.8.1

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

145
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
145
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
146
 # using the given strftime format.
146
 # using the given strftime format.
147
 # html_last_updated_fmt = '%b %d, %Y'
147
 # html_last_updated_fmt = '%b %d, %Y'
148
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
148
+# html_last_updated_fmt = '%Y-%m-%d %H:%M'
149
 
149
 
150
 # If true, SmartyPants will be used to convert quotes and dashes to
150
 # If true, SmartyPants will be used to convert quotes and dashes to
151
 # typographically correct entities.
151
 # typographically correct entities.
190
 
190
 
191
 # -- Options for LaTeX output ---------------------------------------------
191
 # -- Options for LaTeX output ---------------------------------------------
192
 
192
 
193
-latex_elements = {
194
-    # The paper size ('letterpaper' or 'a4paper').
195
-    # 'papersize': 'letterpaper',
196
-
197
-    # The font size ('10pt', '11pt' or '12pt').
198
-    # 'pointsize': '10pt',
199
-
200
-    # Additional stuff for the LaTeX preamble.
201
-    # 'preamble': '',
202
-}
203
-
204
 # Grouping the document tree into LaTeX files. List of tuples
193
 # Grouping the document tree into LaTeX files. List of tuples
205
 # (source start file, target name, title,
194
 # (source start file, target name, title,
206
 #  author, documentclass [howto, manual, or own class]).
195
 #  author, documentclass [howto, manual, or own class]).

+ 2
- 1
requirements.txt View File

6
 iso8601>=0.1.11 # MIT
6
 iso8601>=0.1.11 # MIT
7
 lxml!=3.7.0,>=3.4.1 # BSD
7
 lxml!=3.7.0,>=3.4.1 # BSD
8
 docutils>=0.11 # OSI-Approved Open Source, Public Domain
8
 docutils>=0.11 # OSI-Approved Open Source, Public Domain
9
-sphinx!=1.6.6,!=1.6.7,>=1.6.5 # BSD
9
+sphinx>=1.6.5,!=1.6.6,!=1.6.7,<2.0.0;python_version=='2.7'  # BSD
10
+sphinx>=1.6.5,!=1.6.6,!=1.6.7,!=2.1.0;python_version>='3.4'  # BSD
10
 demjson>=2.2.2 # GLGPLv3+
11
 demjson>=2.2.2 # GLGPLv3+
11
 PyYAML>=3.12 # MIT
12
 PyYAML>=3.12 # MIT

+ 0
- 8
setup.cfg View File

37
      openstack-jsoncheck = os_doc_tools.jsoncheck:main
37
      openstack-jsoncheck = os_doc_tools.jsoncheck:main
38
      openstack-indexpage = os_doc_tools.index:main
38
      openstack-indexpage = os_doc_tools.index:main
39
 
39
 
40
-[build_sphinx]
41
-source-dir = doc/source
42
-build-dir = doc/build
43
-all_files = 1
44
-
45
-[upload_sphinx]
46
-upload-dir = doc/build/html
47
-
48
 [wheel]
40
 [wheel]
49
 universal = 1
41
 universal = 1

+ 15
- 18
sitemap/README.rst View File

47
 ~~~~~~~
47
 ~~~~~~~
48
 
48
 
49
 domain=URL
49
 domain=URL
50
+  Sets the ``domain`` to crawl. Default is ``docs.openstack.org``.
50
 
51
 
51
-   Sets the ``domain`` to crawl. Default is ``docs.openstack.org``.
52
+  For example, to crawl https://developer.openstack.org use the following
53
+  command:
52
 
54
 
53
-   For example, to crawl https://developer.openstack.org use the following
54
-   command:
55
+  .. code-block:: console
55
 
56
 
56
-   .. code-block:: console
57
+     $ scrapy crawl sitemap -a domain=developer.openstack.org
57
 
58
 
58
-      $ scrapy crawl sitemap -a domain=developer.openstack.org
59
-
60
-   The result is available in the ``sitemap_developer.openstack.org.xml`` file.
59
+  The result is available in the ``sitemap_developer.openstack.org.xml`` file.
61
 
60
 
62
 urls=URL
61
 urls=URL
62
+  You can define a set of additional start URLs using the ``urls`` attribute.
63
+  Separate multiple URLs with ``,``.
63
 
64
 
64
-   You can define a set of additional start URLs using the ``urls`` attribute.
65
-   Separate multiple URLs with ``,``.
66
-
67
-   For example:
65
+  For example:
68
 
66
 
69
-   .. code-block:: console
67
+  .. code-block:: console
70
 
68
 
71
-      $ scrapy crawl sitemap -a domain=developer.openstack.org -a urls="https://developer.openstack.org/de/api-guide/quick-start/"
69
+     $ scrapy crawl sitemap -a domain=developer.openstack.org -a urls="https://developer.openstack.org/de/api-guide/quick-start/"
72
 
70
 
73
 LOG_FILE=FILE
71
 LOG_FILE=FILE
72
+  Write log messages to the specified file.
74
 
73
 
75
-   Write log messages to the specified file.
76
-
77
-   For example, to write to ``scrapy.log``:
74
+  For example, to write to ``scrapy.log``:
78
 
75
 
79
-   .. code-block:: console
76
+  .. code-block:: console
80
 
77
 
81
-      $ scrapy crawl sitemap -s LOG_FILE=scrapy.log
78
+     $ scrapy crawl sitemap -s LOG_FILE=scrapy.log

+ 1
- 1
test-requirements.txt View File

11
 pylint==1.7.1 # GPLv2
11
 pylint==1.7.1 # GPLv2
12
 
12
 
13
 reno>=2.5.0 # Apache-2.0
13
 reno>=2.5.0 # Apache-2.0
14
-openstackdocstheme>=1.18.1 # Apache-2.0
14
+openstackdocstheme>=1.20.0 # Apache-2.0
15
 stestr>=2.0.0 # Apache-2.0
15
 stestr>=2.0.0 # Apache-2.0
16
 
16
 
17
 # mock object framework
17
 # mock object framework

+ 3
- 2
tox.ini View File

24
     doc8 -e txt -e rst doc/source/ HACKING.rst
24
     doc8 -e txt -e rst doc/source/ HACKING.rst
25
     # Run bashate during pep8 runs to ensure violations are caught by
25
     # Run bashate during pep8 runs to ensure violations are caught by
26
     # the check and gate queues.
26
     # the check and gate queues.
27
-    bashate bin/doc-tools-check-languages
27
+    bashate bin/doc-tools-check-languages bin/doc-tools-build-rst
28
 
28
 
29
 [testenv:releasenotes]
29
 [testenv:releasenotes]
30
 basepython = python3
30
 basepython = python3
39
 
39
 
40
 [testenv:docs]
40
 [testenv:docs]
41
 basepython = python3
41
 basepython = python3
42
-commands = python setup.py build_sphinx
42
+commands =
43
+  sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
43
 
44
 
44
 [testenv:bindep]
45
 [testenv:bindep]
45
 # Do not install any requirements. We want this to be fast and work even if
46
 # Do not install any requirements. We want this to be fast and work even if

Loading…
Cancel
Save