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 3 months ago
parent
commit
06d7ac27b7

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

# 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

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



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
$ pip install openstack-doc-tools
$ mkvirtualenv openstack-doc-tools
$ pip install openstack-doc-tools

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

openstack-doc-test openstack-doc-test
================== ==================


------------------------------------------------------
-------------------------
OpenStack Validation tool OpenStack Validation tool
------------------------------------------------------
-------------------------


SYNOPSIS SYNOPSIS
======== ========
OPTIONS OPTIONS
======= =======


**General options**
**General options**


**--api-site**
Special handling for api-site and other API repositories
to handle WADL.
**--api-site**
Special handling for api-site and other API repositories
to handle WADL.


**--build-file-exception BUILD_FILE_EXCEPTION**
File that will be skipped during delete and build checks to
generate dependencies. This should be done for invalid XML files
only.
**--build-file-exception BUILD_FILE_EXCEPTION**
File that will be skipped during delete and build checks to
generate dependencies. This should be done for invalid XML files
only.


**--check-build**
Try to build books using modified files.
**--check-build**
Try to build books using modified files.


**--check-deletions**
Check that deleted files are not used.
**--check-deletions**
Check that deleted files are not used.


**--check-links**
Check that linked URLs are valid and reachable.
**--check-links**
Check that linked URLs are valid and reachable.


**--check-niceness**
Check the niceness of files, for example whitespace.
**--check-niceness**
Check the niceness of files, for example whitespace.


**--check-syntax**
Check the syntax of modified files.
**--check-syntax**
Check the syntax of modified files.


**--check-all**
Run all checks (default if no arguments are given).
**--check-all**
Run all checks (default if no arguments are given).


**--config-file PATH**
Path to a config file to use. Multiple config files can be
specified, with values in later files taking precedence.
**--config-file PATH**
Path to a config file to use. Multiple config files can be
specified, with values in later files taking precedence.


**--debug**
Enable debug code.
**--debug**
Enable debug code.


**--file-exception FILE_EXCEPTION**
File that will be skipped during niceness and syntax validation.
**--file-exception FILE_EXCEPTION**
File that will be skipped during niceness and syntax validation.


**--force**
Force the validation of all files and build all books.
**--force**
Force the validation of all files and build all books.


**-h, --help**
Show help message and exit.
**-h, --help**
Show help message and exit.


**--ignore-dir IGNORE_DIR**
Directory to ignore for building of manuals. The parameter can
be passed multiple times to add several directories.
**--ignore-dir IGNORE_DIR**
Directory to ignore for building of manuals. The parameter can
be passed multiple times to add several directories.


**--language LANGUAGE, -l LANGUAGE**
Build translated manual for language in path generate/$LANGUAGE .
**--language LANGUAGE, -l LANGUAGE**
Build translated manual for language in path generate/$LANGUAGE .


**--only-book ONLY_BOOK**
Build each specified manual.
**--only-book ONLY_BOOK**
Build each specified manual.


**--parallel**
Build books in parallel (default).
**--parallel**
Build books in parallel (default).


**--print-unused-files**
Print list of files that are not included anywhere as part of
check-build.
**--print-unused-files**
Print list of files that are not included anywhere as part of
check-build.


**--publish**
Setup content in publish-docs directory for publishing to
external website.
**--publish**
Setup content in publish-docs directory for publishing to
external website.


**--verbose**
Verbose execution.
**--verbose**
Verbose execution.


**--version**
Output version number.
**--version**
Output version number.


FILES FILES
===== =====

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



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

+ 1
- 1
lower-constraints.txt View File

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

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

# 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.


# -- 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]).

+ 2
- 1
requirements.txt View File

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

+ 0
- 8
setup.cfg View File

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

+ 15
- 18
sitemap/README.rst View File

~~~~~~~ ~~~~~~~


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
command:
.. code-block:: console


.. 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.
Separate multiple URLs with ``,``.

For example:
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

+ 1
- 1
test-requirements.txt View File

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

+ 3
- 2
tox.ini View File

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


[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

Loading…
Cancel
Save