openstack
/
openstack-doc-tools
Code Issues Proposed changes

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
This commit is contained in:
Andreas Jaeger 2019-08-11 09:40:40 +02:00
parent a178d4b73c
commit 06d7ac27b7
11 changed files with 83 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/source/conf.py
View File

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

10
doc/source/installation.rst
View File

@ -4,13 +4,13 @@ Installation
At the command line: At the command line:
.. code-block:: console .. code-block:: console
$ pip install openstack-doc-tools $ pip install openstack-doc-tools
Or, if you have virtualenvwrapper installed: Or, if you have virtualenvwrapper installed:
.. code-block:: console .. code-block:: console
$ mkvirtualenv openstack-doc-tools $ mkvirtualenv openstack-doc-tools
$ pip install openstack-doc-tools $ pip install openstack-doc-tools

104
doc/source/man/openstack-doc-test.rst
View File

@ -2,9 +2,9 @@
openstack-doc-test openstack-doc-test
================== ==================
------------------------------------------------------ -------------------------
OpenStack Validation tool OpenStack Validation tool
------------------------------------------------------ -------------------------
SYNOPSIS SYNOPSIS
======== ========
@ -20,77 +20,77 @@ documentation content.
OPTIONS OPTIONS
======= =======
**General options** **General options**
**--api-site** **--api-site**
Special handling for api-site and other API repositories Special handling for api-site and other API repositories
to handle WADL. to handle WADL.
**--build-file-exception BUILD_FILE_EXCEPTION** **--build-file-exception BUILD_FILE_EXCEPTION**
File that will be skipped during delete and build checks to File that will be skipped during delete and build checks to
generate dependencies. This should be done for invalid XML files generate dependencies. This should be done for invalid XML files
only. only.
**--check-build** **--check-build**
Try to build books using modified files. Try to build books using modified files.
**--check-deletions** **--check-deletions**
Check that deleted files are not used. Check that deleted files are not used.
**--check-links** **--check-links**
Check that linked URLs are valid and reachable. Check that linked URLs are valid and reachable.
**--check-niceness** **--check-niceness**
Check the niceness of files, for example whitespace. Check the niceness of files, for example whitespace.
**--check-syntax** **--check-syntax**
Check the syntax of modified files. Check the syntax of modified files.
**--check-all** **--check-all**
Run all checks (default if no arguments are given). Run all checks (default if no arguments are given).
**--config-file PATH** **--config-file PATH**
Path to a config file to use. Multiple config files can be Path to a config file to use. Multiple config files can be
specified, with values in later files taking precedence. specified, with values in later files taking precedence.
**--debug** **--debug**
Enable debug code. Enable debug code.
**--file-exception FILE_EXCEPTION** **--file-exception FILE_EXCEPTION**
File that will be skipped during niceness and syntax validation. File that will be skipped during niceness and syntax validation.
**--force** **--force**
Force the validation of all files and build all books. Force the validation of all files and build all books.
**-h, --help** **-h, --help**
Show help message and exit. Show help message and exit.
**--ignore-dir IGNORE_DIR** **--ignore-dir IGNORE_DIR**
Directory to ignore for building of manuals. The parameter can Directory to ignore for building of manuals. The parameter can
be passed multiple times to add several directories. be passed multiple times to add several directories.
**--language LANGUAGE, -l LANGUAGE** **--language LANGUAGE, -l LANGUAGE**
Build translated manual for language in path generate/$LANGUAGE . Build translated manual for language in path generate/$LANGUAGE .
**--only-book ONLY_BOOK** **--only-book ONLY_BOOK**
Build each specified manual. Build each specified manual.
**--parallel** **--parallel**
Build books in parallel (default). Build books in parallel (default).
**--print-unused-files** **--print-unused-files**
Print list of files that are not included anywhere as part of Print list of files that are not included anywhere as part of
check-build. check-build.
**--publish** **--publish**
Setup content in publish-docs directory for publishing to Setup content in publish-docs directory for publishing to
external website. external website.
**--verbose** **--verbose**
Verbose execution. Verbose execution.
**--version** **--version**
Output version number. Output version number.
FILES FILES
===== =====

4
doc/source/usage.rst
View File

@ -4,6 +4,6 @@ Usage
To use openstack-doc-tools in a project: To use openstack-doc-tools in a project:
.. code-block:: python .. code-block:: python
import os_doc_tools import os_doc_tools

2
lower-constraints.txt
View File

@ -21,7 +21,7 @@ lxml==3.4.1
MarkupSafe==1.0 MarkupSafe==1.0
mccabe==0.2.1 mccabe==0.2.1
mock==2.0.0 mock==2.0.0
openstackdocstheme==1.18.1 openstackdocstheme==1.20.0
pbr==2.0.0 pbr==2.0.0
pep8==1.5.7 pep8==1.5.7
pyflakes==0.8.1 pyflakes==0.8.1

13
releasenotes/source/conf.py
View File

@ -145,7 +145,7 @@ html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format. # using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y' # html_last_updated_fmt = '%b %d, %Y'
html_last_updated_fmt = '%Y-%m-%d %H:%M' # html_last_updated_fmt = '%Y-%m-%d %H:%M'
# If true, SmartyPants will be used to convert quotes and dashes to # If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities. # typographically correct entities.
@ -190,17 +190,6 @@ htmlhelp_basename = 'OpenStack-Doc-Tools-ReleaseNotesdoc'
# -- Options for LaTeX output --------------------------------------------- # -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples # Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, # (source start file, target name, title,
# author, documentclass [howto, manual, or own class]). # author, documentclass [howto, manual, or own class]).

3
requirements.txt
View File

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

8
setup.cfg
View File

@ -37,13 +37,5 @@ console_scripts =
openstack-jsoncheck = os_doc_tools.jsoncheck:main openstack-jsoncheck = os_doc_tools.jsoncheck:main
openstack-indexpage = os_doc_tools.index:main openstack-indexpage = os_doc_tools.index:main
[build_sphinx]
source-dir = doc/source
build-dir = doc/build
all_files = 1
[upload_sphinx]
upload-dir = doc/build/html
[wheel] [wheel]
universal = 1 universal = 1

33
sitemap/README.rst
View File

@ -47,35 +47,32 @@ Options
~~~~~~~ ~~~~~~~
domain=URL domain=URL
Sets the ``domain`` to crawl. Default is ``docs.openstack.org``.
Sets the ``domain`` to crawl. Default is ``docs.openstack.org``. For example, to crawl https://developer.openstack.org use the following
command:
For example, to crawl https://developer.openstack.org use the following .. code-block:: console
command:
.. code-block:: console $ scrapy crawl sitemap -a domain=developer.openstack.org
$ scrapy crawl sitemap -a domain=developer.openstack.org The result is available in the ``sitemap_developer.openstack.org.xml`` file.
The result is available in the ``sitemap_developer.openstack.org.xml`` file.
urls=URL urls=URL
You can define a set of additional start URLs using the ``urls`` attribute.
Separate multiple URLs with ``,``.
You can define a set of additional start URLs using the ``urls`` attribute. For example:
Separate multiple URLs with ``,``.
For example: .. code-block:: console
.. code-block:: console $ scrapy crawl sitemap -a domain=developer.openstack.org -a urls="https://developer.openstack.org/de/api-guide/quick-start/"
$ scrapy crawl sitemap -a domain=developer.openstack.org -a urls="https://developer.openstack.org/de/api-guide/quick-start/"
LOG_FILE=FILE LOG_FILE=FILE
Write log messages to the specified file.
Write log messages to the specified file. For example, to write to ``scrapy.log``:
For example, to write to ``scrapy.log``: .. code-block:: console
.. code-block:: console $ scrapy crawl sitemap -s LOG_FILE=scrapy.log
$ scrapy crawl sitemap -s LOG_FILE=scrapy.log

2
test-requirements.txt
View File

@ -11,7 +11,7 @@ doc8>=0.6.0 # Apache-2.0
pylint==1.7.1 # GPLv2 pylint==1.7.1 # GPLv2
reno>=2.5.0 # Apache-2.0 reno>=2.5.0 # Apache-2.0
openstackdocstheme>=1.18.1 # Apache-2.0 openstackdocstheme>=1.20.0 # Apache-2.0
stestr>=2.0.0 # Apache-2.0 stestr>=2.0.0 # Apache-2.0
# mock object framework # mock object framework

5
tox.ini
View File

@ -24,7 +24,7 @@ commands =
doc8 -e txt -e rst doc/source/ HACKING.rst doc8 -e txt -e rst doc/source/ HACKING.rst
# Run bashate during pep8 runs to ensure violations are caught by # Run bashate during pep8 runs to ensure violations are caught by
# the check and gate queues. # the check and gate queues.
bashate bin/doc-tools-check-languages bashate bin/doc-tools-check-languages bin/doc-tools-build-rst
[testenv:releasenotes] [testenv:releasenotes]
basepython = python3 basepython = python3
@ -39,7 +39,8 @@ commands = {posargs}
[testenv:docs] [testenv:docs]
basepython = python3 basepython = python3
commands = python setup.py build_sphinx commands =
sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
[testenv:bindep] [testenv:bindep]
# Do not install any requirements. We want this to be fast and work even if # Do not install any requirements. We want this to be fast and work even if