소스 검색

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 개월 전
부모
커밋
06d7ac27b7
11개의 변경된 파일83개의 추가작업 그리고 103개의 파일을 삭제
  1. 1
    1
      doc/source/conf.py
  2. 5
    5
      doc/source/installation.rst
  3. 52
    52
      doc/source/man/openstack-doc-test.rst
  4. 2
    2
      doc/source/usage.rst
  5. 1
    1
      lower-constraints.txt
  6. 1
    12
      releasenotes/source/conf.py
  7. 2
    1
      requirements.txt
  8. 0
    8
      setup.cfg
  9. 15
    18
      sitemap/README.rst
  10. 1
    1
      test-requirements.txt
  11. 3
    2
      tox.ini

+ 1
- 1
doc/source/conf.py 파일 보기

@@ -66,7 +66,7 @@ html_theme = 'openstackdocs'
66 66
 # So that we can enable "log-a-bug" links from each output HTML page, this
67 67
 # variable must be set to a format that includes year, month, day, hours and
68 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 71
 # Output file base name for HTML help builder.
72 72
 htmlhelp_basename = '%sdoc' % project

+ 5
- 5
doc/source/installation.rst 파일 보기

@@ -4,13 +4,13 @@ Installation
4 4
 
5 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 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 파일 보기

@@ -2,9 +2,9 @@
2 2
 openstack-doc-test
3 3
 ==================
4 4
 
5
-------------------------------------------------------
5
+-------------------------
6 6
 OpenStack Validation tool
7
-------------------------------------------------------
7
+-------------------------
8 8
 
9 9
 SYNOPSIS
10 10
 ========
@@ -20,77 +20,77 @@ documentation content.
20 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 95
 FILES
96 96
 =====

+ 2
- 2
doc/source/usage.rst 파일 보기

@@ -4,6 +4,6 @@ Usage
4 4
 
5 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 파일 보기

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

+ 1
- 12
releasenotes/source/conf.py 파일 보기

@@ -145,7 +145,7 @@ html_static_path = ['_static']
145 145
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
146 146
 # using the given strftime format.
147 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 150
 # If true, SmartyPants will be used to convert quotes and dashes to
151 151
 # typographically correct entities.
@@ -190,17 +190,6 @@ htmlhelp_basename = 'OpenStack-Doc-Tools-ReleaseNotesdoc'
190 190
 
191 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 193
 # Grouping the document tree into LaTeX files. List of tuples
205 194
 # (source start file, target name, title,
206 195
 #  author, documentclass [howto, manual, or own class]).

+ 2
- 1
requirements.txt 파일 보기

@@ -6,6 +6,7 @@ pbr!=2.1.0,>=2.0.0 # Apache-2.0
6 6
 iso8601>=0.1.11 # MIT
7 7
 lxml!=3.7.0,>=3.4.1 # BSD
8 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 11
 demjson>=2.2.2 # GLGPLv3+
11 12
 PyYAML>=3.12 # MIT

+ 0
- 8
setup.cfg 파일 보기

@@ -37,13 +37,5 @@ console_scripts =
37 37
      openstack-jsoncheck = os_doc_tools.jsoncheck:main
38 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 40
 [wheel]
49 41
 universal = 1

+ 15
- 18
sitemap/README.rst 파일 보기

@@ -47,35 +47,32 @@ Options
47 47
 ~~~~~~~
48 48
 
49 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 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 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 파일 보기

@@ -11,7 +11,7 @@ doc8>=0.6.0 # Apache-2.0
11 11
 pylint==1.7.1 # GPLv2
12 12
 
13 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 15
 stestr>=2.0.0 # Apache-2.0
16 16
 
17 17
 # mock object framework

+ 3
- 2
tox.ini 파일 보기

@@ -24,7 +24,7 @@ commands =
24 24
     doc8 -e txt -e rst doc/source/ HACKING.rst
25 25
     # Run bashate during pep8 runs to ensure violations are caught by
26 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 29
 [testenv:releasenotes]
30 30
 basepython = python3
@@ -39,7 +39,8 @@ commands = {posargs}
39 39
 
40 40
 [testenv:docs]
41 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 45
 [testenv:bindep]
45 46
 # Do not install any requirements. We want this to be fast and work even if

Loading…
취소
저장