[contributor] reorganize documentation tools
Reorganizes the Documentation tools section basing on the principles of topic-based authoring. Co-Authored-By: OlgaGusarenko <ogusarenko@mirantis.com> Change-Id: I2f23828672dea091279ee53650275ed9ca48705b Implements: blueprint contributor-guide-reorg
This commit is contained in:
KATO Tomoyuki
@@ -1,23 +1,24 @@
|
|||||||
.. _doc-tools:
|
.. _doc-tools:
|
||||||
|
|
||||||
===================
|
=========================
|
||||||
openstack-doc-tools
|
Using documentation tools
|
||||||
===================
|
=========================
|
||||||
|
|
||||||
The `openstack-doc-tools <https://github.com/openstack/openstack-doc-tools>`_
|
The OpenStack documentation toolkit includes a number of scripts used
|
||||||
repository contains tools used by the OpenStack Documentation project.
|
for performing automated tasks to maintain the OpenStack documentation
|
||||||
|
project. For example, there are tools that generate configuration and
|
||||||
|
command-line interface references, generate a sitemap, check niceness,
|
||||||
|
synchronize files used across multiple repositories, and others.
|
||||||
|
|
||||||
This chapter provides a general overview of the tools. Detailed documentation
|
This section provides an overview of the documentation tools and their
|
||||||
is available at
|
location, explains how to install, configure, use, and contribute to them.
|
||||||
https://github.com/openstack/openstack-doc-tools/tree/master/doc/source.
|
|
||||||
|
|
||||||
**Contents**
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
|
doc-tools/scripts.rst
|
||||||
doc-tools/installation.rst
|
doc-tools/installation.rst
|
||||||
doc-tools/configuration.rst
|
doc-tools/configuration.rst
|
||||||
doc-tools/contributing.rst
|
doc-tools/cli-reference.rst
|
||||||
doc-tools/scripts.rst
|
|
||||||
doc-tools/openstack-doc-test.rst
|
doc-tools/openstack-doc-test.rst
|
||||||
|
doc-tools/contributing.rst
|
||||||
|
|||||||
122
doc/contributor-guide/source/doc-tools/cli-reference.rst
Normal file
122
doc/contributor-guide/source/doc-tools/cli-reference.rst
Normal file
@@ -0,0 +1,122 @@
|
|||||||
|
=========================================
|
||||||
|
Generate Command-Line Interface Reference
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
The OpenStack Command-Line Interface (CLI) Reference source files are stored
|
||||||
|
in the ``openstack-manuals`` repository. The majority of files are
|
||||||
|
automatically generated and should not be modified manually. To update
|
||||||
|
automatically generated files, use the ``openstack-auto-commands`` tool found
|
||||||
|
in the `openstack-doc-tools <https://git.openstack.org/cgit/openstack/openstack-doc-tools>`_
|
||||||
|
repository.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
See ``os_doc_tools/resources/clients.yaml`` for a list of
|
||||||
|
supported clients.
|
||||||
|
|
||||||
|
To distinguish an automatically generated file from the file that can be
|
||||||
|
edited manually, verify it contains the warning at the top of the file:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
## WARNING ######################################
|
||||||
|
This file is automatically generated, do not edit
|
||||||
|
#################################################
|
||||||
|
|
||||||
|
|
||||||
|
Update CLI documentation using an automated submission
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The ``openstack-doc-tools`` repository contains the script to automate
|
||||||
|
submission of an update to OpenStack clients CLI documentation.
|
||||||
|
|
||||||
|
To update CLI documentation and automatically submit a change request:
|
||||||
|
|
||||||
|
#. Clone the tools repository:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ git clone git://git.openstack.org/openstack/openstack-doc-tools
|
||||||
|
$ cd openstack-doc-tools/bin
|
||||||
|
|
||||||
|
#. Run the automated script:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ ./doc-tools-update-cli-reference <CLIENT_NAME>
|
||||||
|
|
||||||
|
The script generates a virtual environment, installs necessary software,
|
||||||
|
generates the corresponding CLI documentation file based on the latest
|
||||||
|
CLI client version, and commits the newly generated file locally.
|
||||||
|
|
||||||
|
#. Verify that the file has built correctly.
|
||||||
|
#. If you are satisfied with the generation, submit the change request for
|
||||||
|
review:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ cd openstack-manuals
|
||||||
|
$ git review
|
||||||
|
|
||||||
|
.. important::
|
||||||
|
|
||||||
|
If inspection of the generated file reveals typographical errors
|
||||||
|
or incorrect content, **do not fix these**. They must be fixed
|
||||||
|
in the corresponding client repository (typically by adjusting
|
||||||
|
the help strings for the various commands). Once the change
|
||||||
|
has merged and a new client released, a new CLI documentation file
|
||||||
|
can be generated with the updated content.
|
||||||
|
|
||||||
|
|
||||||
|
Update CLI documentation using a manual submission
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
To re-generate CLI documentation and submit it manually:
|
||||||
|
|
||||||
|
#. Install ``openstack-doc-tools``:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ pip install openstack-doc-tools
|
||||||
|
|
||||||
|
#. Сlone the ``openstack-doc-tools`` repository to verify that you have
|
||||||
|
the latest version of the tool. This is also required if you reconfigure
|
||||||
|
the tool to generate a proper file.
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ pushd <work_dir>
|
||||||
|
$ git clone git://git.openstack.org/openstack/openstack-doc-tools
|
||||||
|
$ cd openstack-doc-tools
|
||||||
|
$ pip install .
|
||||||
|
$ cd ..
|
||||||
|
|
||||||
|
#. Change to the ``doc/cli-reference/source`` directory within
|
||||||
|
``openstack-manuals``:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ cd /path/to/openstack-manuals/doc/cli-reference/source
|
||||||
|
|
||||||
|
#. Generate CLI documentation using :command:`openstack-auto-commands`:
|
||||||
|
|
||||||
|
* To generate all CLI files, run:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ openstack-auto-commands --all
|
||||||
|
|
||||||
|
* To generate a specific CLI file, run:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ openstack-auto-commands <CLIENT_NAME>
|
||||||
|
|
||||||
|
* To check a list of available options, run:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ openstack-auto-commands --help
|
||||||
|
|
||||||
|
#. Once you finish updating the generated files, commit the changes and
|
||||||
|
:doc:`submit it on review in the usual manner<../quickstart/first-timers>`.
|
||||||
@@ -1,47 +1,47 @@
|
|||||||
=============
|
=======================================
|
||||||
Configuration
|
Configure OpenStack documentation tools
|
||||||
=============
|
=======================================
|
||||||
|
|
||||||
If you run the ``openstack-doc-test --check-build``, it will copy all
|
OpenStack documentation tools use the ``doc-test.conf`` file as a source for
|
||||||
the books to the directory ``publish-docs`` in the top-level directory
|
the default settings.
|
||||||
of your repository.
|
|
||||||
|
|
||||||
By default, it outputs a directory with the same name as the directory
|
By default, the :command:`openstack-doc-test --check-build` copies the books
|
||||||
where the ``pom.xml`` file lives in, such as ``glossary``. You can
|
to the ``publish-docs`` directory in the top-level directory of a project's
|
||||||
also check the output of the build job for the name.
|
repository. You can modify the default settings for the books that require
|
||||||
|
special treatment by configuring the following options:
|
||||||
|
|
||||||
Some books need special treatment and there are three options you can
|
book
|
||||||
set in the file ``doc-test.conf``:
|
The name of a book that needs special treatment
|
||||||
|
|
||||||
* ``book`` - the name of a book that needs special treatment
|
target_dir
|
||||||
* ``target_dir`` - the path of subdirectory starting at ``target``
|
The path of subdirectory starting at ``target`` that is the root for
|
||||||
that is the root for publishing
|
publishing
|
||||||
* ``publish_dir`` - a new name to publish a book under
|
|
||||||
|
|
||||||
As an example, to publish the compute-api version 2 in the directory
|
publish_dir
|
||||||
``publish-docs/api/openstack-compute/2``, use::
|
A new name to publish a book under
|
||||||
|
|
||||||
book = openstack-compute-api-2
|
|
||||||
target_dir = target/docbkx/webhelp/api/openstack-compute/2
|
|
||||||
publish_dir = api/openstack-compute/2
|
|
||||||
|
|
||||||
These options can be specified multiple times and should
|
|
||||||
always be used this way. You do not need to set ``publish_dir`` but if
|
|
||||||
you set it, you need to use it every time.
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
These are optional settings. The logic in the tool is
|
You can specify these options multiple times and should always use them
|
||||||
sufficient for many of the books.
|
this way.
|
||||||
|
|
||||||
* Source: http://git.openstack.org/cgit/openstack/openstack-doc-tools
|
You do not need to set ``publish_dir`` but if you set it, you need to use
|
||||||
* Bugs: http://bugs.launchpad.net/openstack-manuals
|
it every time.
|
||||||
|
|
||||||
|
As an example, to publish the compute-api version 2 to
|
||||||
|
``publish-docs/api/openstack-compute/2``, edit ``doc-test.conf`` as follows:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
book = openstack-compute-api-2
|
||||||
|
target_dir = target/docbkx/webhelp/api/openstack-compute/2
|
||||||
|
publish_dir = api/openstack-compute/2
|
||||||
|
|
||||||
|
|
||||||
Sample doc-test.conf file
|
Sample doc-test.conf file
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
.. code::
|
.. code-block:: none
|
||||||
|
|
||||||
[DEFAULT]
|
[DEFAULT]
|
||||||
|
|
||||||
|
|||||||
@@ -1,50 +1,57 @@
|
|||||||
============
|
===========================================
|
||||||
Contributing
|
Contribute to OpenStack documentation tools
|
||||||
============
|
===========================================
|
||||||
|
|
||||||
If you would like to contribute to the development of the
|
If you would like to contribute to OpenStack documentation tools, you are
|
||||||
``openstack-doc-tools``, follow the steps in the `Developers Guide
|
welcome to submit a patch or file a bug against the toolkit.
|
||||||
<http://docs.openstack.org/infra/manual/developers.html>`_.
|
|
||||||
|
|
||||||
Once those steps have been completed, changes to OpenStack
|
Contribute to the tool development
|
||||||
should be submitted for review via the Gerrit tool, following
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
the `gerrit workflow
|
|
||||||
<http://docs.openstack.org/infra/manual/developers.html#development-workflow>`_
|
|
||||||
|
|
||||||
Pull requests submitted through GitHub will be ignored.
|
To contribute to the development of ``openstack-doc-tools``, proceed with
|
||||||
|
the following steps:
|
||||||
|
|
||||||
Bugs should be filed on `Launchpad
|
#. Complete the procedures described
|
||||||
<https://bugs.launchpad.net/openstack-manuals>`_, not GitHub.
|
in the `Developers Guide <http://docs.openstack.org/infra/manual/developers.html>`_.
|
||||||
|
|
||||||
|
#. Follow `OpenStack Style Commandments <http://docs.openstack.org/developer/hacking/>`_
|
||||||
|
while developing improvements for the tool.
|
||||||
|
|
||||||
|
#. Run tests before you submit your change request.
|
||||||
|
|
||||||
|
For now, the documentation toolkit is tested with basic ``flake8``
|
||||||
|
and ``bashate`` tests. A test suite would be welcome.
|
||||||
|
|
||||||
|
Since the ``openstack-doc-test`` tool is used for gating of
|
||||||
|
the OpenStack documentation repositories, test building of
|
||||||
|
these repositories with any changes done within the tool repository:
|
||||||
|
|
||||||
|
#. Install ``openstack-doc-tools`` locally.
|
||||||
|
#. Check out the gated repositories.
|
||||||
|
The repositories gated by ``openstack-doc-tools`` are:
|
||||||
|
|
||||||
|
* api-site
|
||||||
|
* openstack-manuals
|
||||||
|
|
||||||
|
#. Run :command:`tox` inside of each gated repository.
|
||||||
|
|
||||||
|
#. Submit your change for review through the Gerrit tool as described
|
||||||
|
in the `gerrit workflow <http://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
Pull requests submitted through GitHub will be ignored.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
To be able to run ``"tox -e py27"`` successfully locally, add
|
To be able to run ``"tox -e py27"`` successfully locally, add
|
||||||
``jinja2`` and ``markupsafe`` to your local ``test-requirements.txt``
|
``jinja2`` and ``markupsafe`` to your local ``test-requirements.txt``
|
||||||
file so the two get installed in your local virtual environment.
|
file to have them installed in your local virtual environment.
|
||||||
|
|
||||||
|
|
||||||
Style commandments
|
File a bug against the tools
|
||||||
~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Read the `OpenStack Style Commandments
|
If you experience an issue while using the ``openstack-doc-test`` tool,
|
||||||
<http://docs.openstack.org/developer/hacking/>`_.
|
file a bug on Launchpad in the `openstack-manuals project
|
||||||
|
<https://bugs.launchpad.net/openstack-manuals>`_, not on GitHub.
|
||||||
|
|
||||||
Running tests
|
|
||||||
~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
So far these tools are tested with only basic flake8 and bashate tests. A test
|
|
||||||
suite would be welcome!
|
|
||||||
|
|
||||||
Since the ``openstack-doc-test`` tool is used for gating of the OpenStack
|
|
||||||
documentation repositories, test building of these repositories with
|
|
||||||
any changes done here.
|
|
||||||
|
|
||||||
Testing can be done with simply a local install of
|
|
||||||
``openstack-doc-tools``, then checking out the gated repositories and
|
|
||||||
running: ``tox`` inside of each.
|
|
||||||
|
|
||||||
The repositories gated by ``openstack-doc-tools`` are:
|
|
||||||
|
|
||||||
* api-site
|
|
||||||
* openstack-manuals
|
|
||||||
|
|||||||
@@ -1,22 +1,29 @@
|
|||||||
======================
|
.. _doc-toolsd-installation:
|
||||||
Installation and usage
|
|
||||||
======================
|
|
||||||
|
|
||||||
At the command line:
|
=====================================
|
||||||
|
Install OpenStack documentation tools
|
||||||
|
=====================================
|
||||||
|
|
||||||
.. code::
|
To install the documentation toolkit:
|
||||||
|
|
||||||
$ pip install openstack-doc-tools
|
#. Verify that you have installed
|
||||||
|
the `prerequisites <https://github.com/openstack/openstack-doc-tools/blob/master/README.rst>`_.
|
||||||
|
|
||||||
Or, if you have ``virtualenvwrapper`` installed:
|
#. Install the ``openstack-doc-tools`` package:
|
||||||
|
|
||||||
.. code::
|
.. code-block:: console
|
||||||
|
|
||||||
$ mkvirtualenv openstack-doc-tools
|
$ pip install openstack-doc-tools
|
||||||
$ pip install openstack-doc-tools
|
|
||||||
|
|
||||||
To use openstack-doc-tools in a project:
|
If you have ``virtualenvwrapper`` installed, run:
|
||||||
|
|
||||||
.. code::
|
.. code::
|
||||||
|
|
||||||
import os_doc_tools
|
$ mkvirtualenv openstack-doc-tools
|
||||||
|
$ pip install openstack-doc-tools
|
||||||
|
|
||||||
|
#. To use ``openstack-doc-tools``, import the tools to a project:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
import os_doc_tools
|
||||||
|
|||||||
@@ -1,117 +1,89 @@
|
|||||||
.. _openstack-doc-test:
|
.. _openstack-doc-test:
|
||||||
|
|
||||||
==================
|
========================================
|
||||||
openstack-doc-test
|
Validate OpenStack documentation content
|
||||||
==================
|
========================================
|
||||||
|
|
||||||
OpenStack Validation tool
|
To test the validity of the OpenStack documentation content, use
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
the :command:`openstack-doc-test [options]` command with the following
|
||||||
|
available options:
|
||||||
|
|
||||||
SYNOPSIS
|
.. note::
|
||||||
--------
|
|
||||||
|
|
||||||
openstack-doc-test [options]
|
For option processing, the ``openstack-doc-test`` tool reads
|
||||||
|
the `doc-test.conf` in the top-level directory of the git repository.
|
||||||
|
|
||||||
DESCRIPTION
|
--api-site
|
||||||
-----------
|
Special handling for api-site and other API repositories
|
||||||
|
to handle WADL.
|
||||||
|
|
||||||
openstack-doc-test allows to test the validity of the OpenStack
|
--build-file-exception BUILD_FILE_EXCEPTION
|
||||||
documentation content.
|
File that will be skipped during delete and build checks to
|
||||||
|
generate dependencies. This should be done for invalid XML files only.
|
||||||
|
|
||||||
OPTIONS
|
--check-build
|
||||||
-------
|
Try to build books using modified files.
|
||||||
|
|
||||||
**General options**
|
--check-deletions
|
||||||
|
Check that deleted files are not used.
|
||||||
|
|
||||||
**--api-site**
|
--check-links
|
||||||
Special handling for api-site and other API repositories
|
Check that linked URLs are valid and reachable.
|
||||||
to handle WADL.
|
|
||||||
|
|
||||||
**--build-file-exception BUILD_FILE_EXCEPTION**
|
--check-niceness
|
||||||
File that will be skipped during delete and build checks to
|
Check the niceness of files, for example whitespace.
|
||||||
generate dependencies. This should be done for invalid XML files
|
|
||||||
only.
|
|
||||||
|
|
||||||
**--check-build**
|
--check-syntax
|
||||||
Try to build books using modified files.
|
Check the syntax of modified files.
|
||||||
|
|
||||||
**--check-deletions**
|
--check-all
|
||||||
Check that deleted files are not used.
|
Run all checks (default if no arguments are given).
|
||||||
|
|
||||||
**--check-links**
|
--config-file PATH
|
||||||
Check that linked URLs are valid and reachable.
|
Path to a config file to use. Multiple config files can be
|
||||||
|
specified, with values in later files taking precedence.
|
||||||
|
|
||||||
**--check-niceness**
|
--debug
|
||||||
Check the niceness of files, for example whitespace.
|
Enable debug code.
|
||||||
|
|
||||||
**--check-syntax**
|
--file-exception FILE_EXCEPTION
|
||||||
Check the syntax of modified files.
|
File that will be skipped during niceness and syntax validation.
|
||||||
|
|
||||||
**--check-all**
|
--force
|
||||||
Run all checks (default if no arguments are given).
|
Force the validation of all files and build all books.
|
||||||
|
|
||||||
**--config-file PATH**
|
-h, --help
|
||||||
Path to a config file to use. Multiple config files can be
|
Show help message and exit.
|
||||||
specified, with values in later files taking precedence.
|
|
||||||
|
|
||||||
**--debug**
|
--ignore-dir IGNORE_DIR
|
||||||
Enable debug code.
|
Directory to ignore for building of manuals. The parameter can
|
||||||
|
be passed multiple times to add several directories.
|
||||||
|
|
||||||
**--file-exception FILE_EXCEPTION**
|
--language LANGUAGE, -l LANGUAGE
|
||||||
File that will be skipped during niceness and syntax validation.
|
Build translated manual for language in path generate/$LANGUAGE .
|
||||||
|
|
||||||
**--force**
|
--only-book ONLY_BOOK
|
||||||
Force the validation of all files and build all books.
|
Build each specified manual.
|
||||||
|
|
||||||
**-h, --help**
|
--parallel
|
||||||
Show help message and exit.
|
Build books in parallel (default).
|
||||||
|
|
||||||
**--ignore-dir IGNORE_DIR**
|
--print-unused-files
|
||||||
Directory to ignore for building of manuals. The parameter can
|
Print list of files that are not included anywhere as part of
|
||||||
be passed multiple times to add several directories.
|
check-build.
|
||||||
|
|
||||||
**--language LANGUAGE, -l LANGUAGE**
|
--publish
|
||||||
Build translated manual for language in path generate/$LANGUAGE .
|
Setup content in publish-docs directory for publishing to
|
||||||
|
external website.
|
||||||
|
|
||||||
**--only-book ONLY_BOOK**
|
--verbose
|
||||||
Build each specified manual.
|
Verbose execution.
|
||||||
|
|
||||||
**--parallel**
|
--version
|
||||||
Build books in parallel (default).
|
Output version number.
|
||||||
|
|
||||||
**--print-unused-files**
|
Building of books generates the following output in the top-level directory
|
||||||
Print list of files that are not included anywhere as part of
|
of the repository:
|
||||||
check-build.
|
|
||||||
|
|
||||||
**--publish**
|
* The ``publish-docs`` directory with a copy of the build results.
|
||||||
Setup content in publish-docs directory for publishing to
|
* A log file for each book named ``build-${book}.log.gz``.
|
||||||
external website.
|
|
||||||
|
|
||||||
**--verbose**
|
|
||||||
Verbose execution.
|
|
||||||
|
|
||||||
**--version**
|
|
||||||
Output version number.
|
|
||||||
|
|
||||||
FILES
|
|
||||||
-----
|
|
||||||
|
|
||||||
Reads the file `doc-test.conf` in the top-level directory of the git
|
|
||||||
repository for option processing.
|
|
||||||
|
|
||||||
Building of books will generate in the top-level directory of the git
|
|
||||||
repository:
|
|
||||||
|
|
||||||
* a directory `publish-docs` with a copy of the build results.
|
|
||||||
* for each book build a log file named `build-${book}.log.gz`.
|
|
||||||
|
|
||||||
SEE ALSO
|
|
||||||
--------
|
|
||||||
|
|
||||||
* `OpenStack Documentation <http://wiki.openstack.org/wiki/Documentation>`_
|
|
||||||
|
|
||||||
Bugs
|
|
||||||
----
|
|
||||||
|
|
||||||
* openstack-doc-tools is hosted on Launchpad so you can view current
|
|
||||||
bugs at `openstack-manuals <https://bugs.launchpad.net/openstack-manuals/>`_
|
|
||||||
|
|||||||
@@ -1,22 +1,26 @@
|
|||||||
=======
|
================
|
||||||
Scripts
|
Scripts overview
|
||||||
=======
|
================
|
||||||
|
|
||||||
|
This section provides an overview of scripts used by the OpenStack
|
||||||
|
documentation project grouped by repositories they are stored in.
|
||||||
|
|
||||||
|
|
||||||
openstack-doc-tools repository
|
openstack-doc-tools repository
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
autogenerate_config_docs
|
autogenerate_config_docs
|
||||||
Generate configuration references published on
|
Generates configuration references published at
|
||||||
http://docs.openstack.org/mitaka/config-reference/.
|
http://docs.openstack.org/mitaka/config-reference/.
|
||||||
|
|
||||||
build_environment directory (deprecated)
|
build_environment directory (deprecated)
|
||||||
A Vagrant environment for working with the guides.
|
A Vagrant environment for working with the guides.
|
||||||
|
|
||||||
cleanup directory
|
cleanup directory
|
||||||
Manually clean up documentation files.
|
Manually cleans up documentation files.
|
||||||
|
|
||||||
sitemap
|
sitemap
|
||||||
Generate the sitemap.xml file.
|
Generates the ``sitemap.xml`` file.
|
||||||
|
|
||||||
bin
|
bin
|
||||||
Contains scripts for building documents in the ``openstack-manuals``
|
Contains scripts for building documents in the ``openstack-manuals``
|
||||||
@@ -26,19 +30,19 @@ os_doc_tools directory
|
|||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
openstack-doc-test
|
openstack-doc-test
|
||||||
Check niceness of the documentation. Tests links, whitespace, line-endings.
|
Checks niceness of the documentation. Tests links, whitespace, line-endings.
|
||||||
See :ref:`openstack-doc-test`.
|
See :ref:`openstack-doc-test`.
|
||||||
|
|
||||||
openstack-autohelp
|
openstack-autohelp
|
||||||
Helper script run from the git repo by ``autogenerate_config_docs``.
|
A helper script run from the git repository by ``autogenerate_config_docs``.
|
||||||
|
|
||||||
openstack-auto-commands
|
openstack-auto-commands
|
||||||
Generate the command line reference published at
|
Generates the command-line interface reference published at
|
||||||
http://docs.openstack.org/cli-reference/. A helper script to use this
|
http://docs.openstack.org/cli-reference/. A helper script to use this
|
||||||
tool is available at ``bin/doc-tools-update-cli-reference``.
|
tool is available at ``bin/doc-tools-update-cli-reference``.
|
||||||
|
|
||||||
openstack-jsoncheck
|
openstack-jsoncheck
|
||||||
Check JSON files. Used for the API guides
|
Checks JSON files. Used for the API guides.
|
||||||
|
|
||||||
|
|
||||||
openstack-manuals repository
|
openstack-manuals repository
|
||||||
@@ -49,11 +53,11 @@ Several scripts currently reside in the `openstack-manuals
|
|||||||
beneficial to consolidate these into the ``openstack-doc-tools`` repository.
|
beneficial to consolidate these into the ``openstack-doc-tools`` repository.
|
||||||
|
|
||||||
www-generator.py
|
www-generator.py
|
||||||
Generate static, template-based html files for http://docs.openstack.org/.
|
Generates static, template-based HTML files for http://docs.openstack.org/.
|
||||||
|
|
||||||
sync-projects.sh
|
sync-projects.sh
|
||||||
Synchronizes the **Glossary**, common files, and some translations
|
Synchronizes the **Glossary**, common files, and some translations
|
||||||
across multiple repos, including ``api-site`` and ``security-doc``.
|
across multiple repositories, including ``api-site`` and ``security-doc``.
|
||||||
|
|
||||||
publishdocs.sh
|
publishdocs.sh
|
||||||
Publishdocs job uses this script to publish documentation to
|
Publishdocs job uses this script to publish documentation to
|
||||||
|
|||||||
@@ -30,7 +30,6 @@ Contents
|
|||||||
ui-text-guidelines.rst
|
ui-text-guidelines.rst
|
||||||
rst-conv.rst
|
rst-conv.rst
|
||||||
json-conv.rst
|
json-conv.rst
|
||||||
tools-and-content-overview.rst
|
|
||||||
docs-builds.rst
|
docs-builds.rst
|
||||||
build-locally.rst
|
build-locally.rst
|
||||||
doc-tools.rst
|
doc-tools.rst
|
||||||
|
|||||||
@@ -1,254 +0,0 @@
|
|||||||
.. _tools_and_content:
|
|
||||||
|
|
||||||
==========================
|
|
||||||
Tools and content overview
|
|
||||||
==========================
|
|
||||||
|
|
||||||
While in the past the documentation team used DocBook format, the guides are
|
|
||||||
now being converted from DocBook to ReStructured Text (RST). For more
|
|
||||||
information on the conversion, see `Doc Migration from DocBook to RST`_.
|
|
||||||
|
|
||||||
To work on the RST source files, find the :file:`/doc/guide/source/` directory
|
|
||||||
in a given OpenStack project. These files are built to
|
|
||||||
*docs.openstack.org/<guide-name>*, for example,
|
|
||||||
http://docs.openstack.org/user-guide.
|
|
||||||
|
|
||||||
Many cross-project manuals are in the
|
|
||||||
http://git.openstack.org/cgit/openstack/openstack-manuals/tree/ project.
|
|
||||||
|
|
||||||
To work on the DocBook and WADL source files for http://developer.openstack.org,
|
|
||||||
look for the http://git.openstack.org/cgit/openstack/api-site project
|
|
||||||
and use the same `development workflow`_.
|
|
||||||
|
|
||||||
The builds are listed on the :ref:`docs_builds` page, showing what
|
|
||||||
source files are built from.
|
|
||||||
|
|
||||||
OpenStack projects
|
|
||||||
~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The OpenStack Documentation program focuses on documentation for the
|
|
||||||
following primary projects:
|
|
||||||
|
|
||||||
* Compute service (nova)
|
|
||||||
* Identity service (keystone)
|
|
||||||
* Image service (glance)
|
|
||||||
* Networking service (neutron)
|
|
||||||
* Block Storage service (cinder)
|
|
||||||
* Object Storage service (swift)
|
|
||||||
|
|
||||||
The Documentation program has cross-project liaisons (CPLs) who assist with
|
|
||||||
subject matter questions, reviews, doc bug triaging, and patching docs. Refer
|
|
||||||
to `documentation cross-project liaisons`_ for a list, and if you are
|
|
||||||
interested in becoming a CPL for docs, contact the Docs PTL.
|
|
||||||
|
|
||||||
These projects have two basic audiences: developers and sysadmins (think
|
|
||||||
operations or dev-ops). The RST-based documentation, because it automatically
|
|
||||||
generates doc from docstrings in the code, is much more for a developer
|
|
||||||
audience.
|
|
||||||
|
|
||||||
The developer documentation serves both Python developers who want to work on
|
|
||||||
OpenStack code and web developers who work with the OpenStack API.
|
|
||||||
|
|
||||||
What docs go where?
|
|
||||||
~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Refer to :ref:`content-specs` for a description of many documents. A long
|
|
||||||
listing of which repos house which documents is at :ref:`docs_builds`.
|
|
||||||
Generally this table describes the patterns for what goes where.
|
|
||||||
|
|
||||||
Specialty teams meet weekly to work on specific documents. For more
|
|
||||||
information about Speciality Teams, including how to get involved, see:
|
|
||||||
`Speciality Teams`_.
|
|
||||||
|
|
||||||
.. TODO (MZ) Change the link above as soon as the page is converted.
|
|
||||||
|
|
||||||
.. important::
|
|
||||||
|
|
||||||
Some content is completely generated using openstack-doc-tools,
|
|
||||||
such as the configuration option tables and the CLI reference information.
|
|
||||||
You will see the following warning in the source file: **<!-- This file is
|
|
||||||
automatically generated, do not edit -->**. When you see this, you can still
|
|
||||||
update the file using the :ref:`doc-tools` tool kit. Please see
|
|
||||||
`Generated files`_.
|
|
||||||
|
|
||||||
.. list-table::
|
|
||||||
:header-rows: 1
|
|
||||||
:widths: 10 20 20
|
|
||||||
:stub-columns: 0
|
|
||||||
:class: borderless
|
|
||||||
|
|
||||||
* - Wiki
|
|
||||||
- RST
|
|
||||||
- WADL/Swagger
|
|
||||||
|
|
||||||
* - Use for project docs.
|
|
||||||
- Use for nearly all guides (migrated to RST), for Python contributor
|
|
||||||
developer documentation, and quick starts.
|
|
||||||
- Use for API reference information built to developer.openstack.org/api-ref.html.
|
|
||||||
|
|
||||||
* - The audience is any project team member of OpenStack.
|
|
||||||
- The audience is Python developers who want to work on the project. For
|
|
||||||
the migrating content, it is for both end users and admin users.
|
|
||||||
- The audience is typically app developers consuming OpenStack services
|
|
||||||
through REST APIs.
|
|
||||||
|
|
||||||
* - Output is per-page at wiki.openstack.org.
|
|
||||||
- Output goes to *docs.openstack.org/<guide-name>* or
|
|
||||||
*docs.openstack.org/developer/<projectname>*.
|
|
||||||
- Output goes to developer.openstack.org/api-ref.html.
|
|
||||||
|
|
||||||
wiki.openstack.org (wikitext or RST)
|
|
||||||
------------------------------------
|
|
||||||
|
|
||||||
The OpenStack wiki contains project docs, legacy specs for blueprints, meeting
|
|
||||||
information, and meeting minutes. If there is a page you want to keep an eye
|
|
||||||
on, add it to your Watchlist (use :menuselection:`Actions > Watch` and see all
|
|
||||||
entries under :menuselection:`YourLogin > Watchlist` on the wiki).
|
|
||||||
|
|
||||||
If you add documentation specific pages, mark them as documentation-related
|
|
||||||
by adding ``[[Category:Documentation]]`` at the end of the page.
|
|
||||||
|
|
||||||
docs.openstack.org/developer/<projectname> (RST)
|
|
||||||
------------------------------------------------
|
|
||||||
|
|
||||||
The RST pages stored with the project code should be written with a developer
|
|
||||||
audience in mind, although you can find there is overlap in what an admin
|
|
||||||
needs to know and what a developer needs to know. High priorities for those
|
|
||||||
sites are wider coverage of doc strings, API doc, i18N methodology, and
|
|
||||||
architecture concepts that can help developers.
|
|
||||||
|
|
||||||
RST stands for ReStructured Text, a simple markup syntax that can be built
|
|
||||||
with Sphinx. Read more at `Sphinx documentation`_.
|
|
||||||
|
|
||||||
Maven plugin
|
|
||||||
------------
|
|
||||||
|
|
||||||
The Cloud Doc Tools Maven plug-in provides a build tool that Jenkins can use
|
|
||||||
to build PDF and HTML from DocBook and WADL source files. It is maintained at http://git.openstack.org/cgit/openstack/clouddocs-maven-plugin/tree/. We
|
|
||||||
track bugs against the output in the openstack-manuals Launchpad project.
|
|
||||||
|
|
||||||
The release notes are available in the Git repository.
|
|
||||||
|
|
||||||
Generated files
|
|
||||||
~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Some documentation files are automatically generated and these should
|
|
||||||
not be modified by hand. They contain a ``do not edit`` warning at
|
|
||||||
the beginning of the file and should only be generated using
|
|
||||||
the :ref:`doc-tools` tool kit.
|
|
||||||
|
|
||||||
CLI reference
|
|
||||||
-------------
|
|
||||||
|
|
||||||
The ``doc/cli-reference`` directory contains documentation for
|
|
||||||
the OpenStack command-line clients. See: `CLI-Reference`_.
|
|
||||||
|
|
||||||
Most of these files are generated using the ``openstack-auto-commands``
|
|
||||||
tool found in the ``openstack-doc-tools`` repository. See the repository
|
|
||||||
file ``os_doc_tools/resources/clients.yaml`` for a list of supported
|
|
||||||
clients. The generated files can be found in ``doc/cli-reference/source``.
|
|
||||||
|
|
||||||
.. important::
|
|
||||||
|
|
||||||
Some files are still manually maintained. If unsure, look for the
|
|
||||||
warning at the top of the file before attempting to re-generate it.
|
|
||||||
|
|
||||||
Automated generation
|
|
||||||
^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Within the ``openstack-doc-tools`` repository, there is a script to
|
|
||||||
automate submission of an update to a client CLI documentation file.
|
|
||||||
The following instructions demonstrate how to use this script
|
|
||||||
using nova as an example client CLI.
|
|
||||||
|
|
||||||
Clone the tools repo.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ git clone git://git.openstack.org/openstack/openstack-doc-tools
|
|
||||||
$ cd openstack-doc-tools/bin
|
|
||||||
|
|
||||||
Run the automated script. This will generate a virtual environment.
|
|
||||||
This will install the necessary software and run the tool to re-generate
|
|
||||||
the file.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ ./doc-tools-update-cli-reference nova
|
|
||||||
|
|
||||||
The script will have cloned the ``openstack-manuals`` repo and created a
|
|
||||||
commit with the newly generated file. Check that the file looks correct
|
|
||||||
and if you are satisfied with it, submit it for review.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ cd openstack-manuals
|
|
||||||
$ git status
|
|
||||||
$ git show
|
|
||||||
$ git review
|
|
||||||
|
|
||||||
.. important::
|
|
||||||
|
|
||||||
If inspection of the generated file reveals typographical errors
|
|
||||||
or incorrect content, *do not fix these.* They must be fixed
|
|
||||||
in the corresponding client repository (typically by adjusting
|
|
||||||
the help strings for the various commands). Once the change
|
|
||||||
has merged and a new client released, a new CLI documentation file
|
|
||||||
can be generated with the updated content.
|
|
||||||
|
|
||||||
Manual generation
|
|
||||||
^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Sometimes it may be necessary to re-generate these files manually.
|
|
||||||
To do this, you must have ``openstack-doc-tools`` installed.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ pip install openstack-doc-tools
|
|
||||||
|
|
||||||
To ensure that you have the latest tool changes, clone the repository.
|
|
||||||
This is also necessary if you make changes to the tool in order to
|
|
||||||
generate a proper file.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ pushd <work_dir>
|
|
||||||
$ git clone git://git.openstack.org/openstack/openstack-doc-tools
|
|
||||||
$ cd openstack-doc-tools
|
|
||||||
$ pip install .
|
|
||||||
$ popd
|
|
||||||
|
|
||||||
Change to the ``doc/cli-reference/source`` directory of your
|
|
||||||
``openstack-manuals`` clone and run the ``openstack-auto-commands``
|
|
||||||
command.
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ cd /path/to/openstack-manuals/doc/cli-reference/source
|
|
||||||
$ openstack-auto-commands --all
|
|
||||||
|
|
||||||
To generate a specific CLI file, run:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ openstack-auto-commands <client_name>
|
|
||||||
|
|
||||||
To check a list of available options, run:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ openstack-auto-commands --help
|
|
||||||
|
|
||||||
Once you finish updating the generated files,
|
|
||||||
submit them in a usual manner.
|
|
||||||
|
|
||||||
.. Links:
|
|
||||||
|
|
||||||
.. _`Doc Migration from DocBook to RST`: https://wiki.openstack.org/wiki/Documentation/Migrate
|
|
||||||
.. _`development workflow`: http://docs.openstack.org/infra/manual/developers.html#development-workflow
|
|
||||||
.. _`Speciality Teams`: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
|
|
||||||
.. _`Generated files`: http://docs.openstack.org/contributor-guide/tools-and-content-overview.html#Generated-files
|
|
||||||
.. _`documentation cross-project liaisons`: https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation
|
|
||||||
.. _`Sphinx documentation`: http://sphinx-doc.org/rest.html
|
|
||||||
.. _`Transition Guide`: http://docbook.org/docs/howto/
|
|
||||||
.. _`CLI-Reference`: http://docs.openstack.org/cli-reference/
|
|
||||||
Reference in New Issue
Block a user