Merge "[contrib-guide] Remove references to removed files"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
c8ea1b3ca0
@ -18,6 +18,4 @@ location, explains how to install, configure, use, and contribute to them.
|
|||||||
doc-tools/scripts.rst
|
doc-tools/scripts.rst
|
||||||
doc-tools/template-generator.rst
|
doc-tools/template-generator.rst
|
||||||
doc-tools/installation.rst
|
doc-tools/installation.rst
|
||||||
doc-tools/cli-reference.rst
|
|
||||||
doc-tools/config-reference.rst
|
|
||||||
doc-tools/contributing.rst
|
doc-tools/contributing.rst
|
||||||
|
|||||||
@ -1,122 +0,0 @@
|
|||||||
=========================================
|
|
||||||
Generate Command-Line Interface Reference
|
|
||||||
=========================================
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
These instructions apply to the guides produced prior to the Pike
|
|
||||||
release. The command line reference guides are now managed in the
|
|
||||||
project repositories.
|
|
||||||
|
|
||||||
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 python-CLIENT_NAME
|
|
||||||
$ 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/source/cli/`` directory within
|
|
||||||
the CLI project. For example:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ cd /path/to/python-glanceclient/doc/source/cli/
|
|
||||||
|
|
||||||
#. Generate CLI documentation using :command:`openstack-auto-commands`:
|
|
||||||
|
|
||||||
* To generate the 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,172 +0,0 @@
|
|||||||
================================
|
|
||||||
Generate Configuration Reference
|
|
||||||
================================
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
These instructions apply to the guides produced prior to the Pike
|
|
||||||
release. The configuration reference guides are now managed in the
|
|
||||||
project repositories using `the Sphinx integration provided by
|
|
||||||
oslo.config
|
|
||||||
<https://docs.openstack.org/oslo.config/latest/reference/sphinxext.html>`__.
|
|
||||||
|
|
||||||
The OpenStack Configuration 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 ``autohelp-wrapper`` tool found in the
|
|
||||||
`openstack-doc-tools <https://git.openstack.org/cgit/openstack/openstack-doc-tools>`_
|
|
||||||
repository.
|
|
||||||
|
|
||||||
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
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
autogenerate_config_docs
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Automatically generate configuration tables to document OpenStack.
|
|
||||||
|
|
||||||
Requirements
|
|
||||||
------------
|
|
||||||
|
|
||||||
Prior to running the generation script, you need to install several
|
|
||||||
development packages.
|
|
||||||
|
|
||||||
On Ubuntu:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ sudo apt-get install python-dev python-pip python-virtualenv \
|
|
||||||
libxml2-dev libxslt1-dev zlib1g-dev \
|
|
||||||
libmysqlclient-dev libpq-dev libffi-dev \
|
|
||||||
libsqlite3-dev libldap2-dev libsasl2-dev \
|
|
||||||
libjpeg-dev liberasurecode-dev
|
|
||||||
|
|
||||||
On RHEL 7 and CentOS 7:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ sudo yum install https://www.rdoproject.org/repos/rdo-release.rpm
|
|
||||||
$ sudo yum update
|
|
||||||
$ sudo yum install python-devel python-pip python-virtualenv \
|
|
||||||
libxml2-devel libxslt-devel zlib-devel \
|
|
||||||
mariadb-devel postgresql-devel libffi-devel \
|
|
||||||
sqlite-devel openldap-devel cyrus-sasl-devel \
|
|
||||||
libjpeg-turbo-devel liberasurecode-devel gcc git
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
* libjpeg is needed for ironic
|
|
||||||
* liberasurecode is needed for swift
|
|
||||||
|
|
||||||
Using the wrapper
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
Use the ``autohelp-wrapper`` script to generate the configuration tables.
|
|
||||||
|
|
||||||
.. important::
|
|
||||||
|
|
||||||
Do not use ``autohelp.py`` manually.
|
|
||||||
|
|
||||||
The ``autohelp-wrapper`` script installs a virtual environment and all the
|
|
||||||
needed dependencies, clones or updates the projects and manuals repositories,
|
|
||||||
then runs the ``autohelp.py`` script in the virtual environment.
|
|
||||||
|
|
||||||
New and updated flagmappings are generated in the ``openstack-manuals``
|
|
||||||
repository (``tools/autogenerate-config-flagmappings/`` directory).
|
|
||||||
|
|
||||||
The workflow is:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ pip install -r requirements.txt
|
|
||||||
$ ./autohelp-wrapper update
|
|
||||||
$ $EDITOR sources/openstack-manuals/tools/autogenerate-config-flagmappings/*.flagmappings
|
|
||||||
$ ./autohelp-wrapper rst
|
|
||||||
|
|
||||||
Check the results in sources/openstack-manuals after completing the workflow.
|
|
||||||
This process generates the tables for all the known projects.
|
|
||||||
|
|
||||||
|
|
||||||
.. important::
|
|
||||||
|
|
||||||
For the Networking service (neutron) project, if the driver/plugin resides
|
|
||||||
outside the neutron repository, then the driver/plugin has to be explicitly
|
|
||||||
installed within the virtual environment to generate the configuration
|
|
||||||
options.
|
|
||||||
|
|
||||||
To generate the mappings and tables for a subset of projects, use the code
|
|
||||||
names as arguments:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ ./autohelp-wrapper update cinder heat
|
|
||||||
|
|
||||||
// edit the mappings files
|
|
||||||
|
|
||||||
$ ./autohelp-wrapper rst cinder heat
|
|
||||||
|
|
||||||
Flagmappings files
|
|
||||||
------------------
|
|
||||||
|
|
||||||
The tool uses flagmapping files to map options to custom categories. Flag
|
|
||||||
mapping files are in the ``tools/autogenerate-config-flagmappings`` folder of
|
|
||||||
the openstack-manuals project. Not all projects use flagmapping files. These
|
|
||||||
projects disabled by a ``$project.disable`` file in that folder. Flag mapping
|
|
||||||
files use the following format:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
|
||||||
|
|
||||||
OPTION_SECTION/OPTION_NAME group1 [group2, ...]
|
|
||||||
|
|
||||||
Groups need to be defined manually to organize the configuration tables.
|
|
||||||
|
|
||||||
The group values can only contain alphanumeric characters, ``_`` and ``-``
|
|
||||||
(they will be used as document IDs).
|
|
||||||
|
|
||||||
To make the table titles more user friendly, create or edit the
|
|
||||||
``PROJECT.headers`` file in the manuals repository. Each line of this file
|
|
||||||
is of the form:
|
|
||||||
|
|
||||||
.. code-block:: none
|
|
||||||
|
|
||||||
GROUP A Nice Title
|
|
||||||
|
|
||||||
Working with branches
|
|
||||||
---------------------
|
|
||||||
|
|
||||||
``autohelp-wrapper`` works on the master branch by default, but you can tell it
|
|
||||||
to work on another branch:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ ./autohelp-wrapper -b stable/liberty update
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
|
|
||||||
The ``-b`` switch does not apply to the ``openstack-manuals`` repository
|
|
||||||
which will be left untouched (no ``git branch``, no ``git update``).
|
|
||||||
|
|
||||||
|
|
||||||
Updating swift options
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
Swift configuration tables are generated using the ``extract_swift_flags.py``
|
|
||||||
script. This script does not use a mapping file, but organizes the tables using
|
|
||||||
the various configuration files and sections. Most of the options must be
|
|
||||||
described manually at the moment.
|
|
||||||
|
|
||||||
Generating configuration difference
|
|
||||||
-----------------------------------
|
|
||||||
|
|
||||||
To generate "New, updated, and deprecated options" for each service,
|
|
||||||
run ``diff_branches.py``. For example:
|
|
||||||
|
|
||||||
.. code-block:: console
|
|
||||||
|
|
||||||
$ ./diff_branches.py stable/liberty stable/mitaka nova
|
|
||||||
@ -9,13 +9,6 @@ documentation project grouped by repositories they are stored in.
|
|||||||
openstack-doc-tools repository
|
openstack-doc-tools repository
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
autogenerate_config_docs
|
|
||||||
Generates configuration references published at
|
|
||||||
https://docs.openstack.org/ocata/config-reference/.
|
|
||||||
|
|
||||||
cleanup directory
|
|
||||||
Manually cleans up documentation files.
|
|
||||||
|
|
||||||
sitemap
|
sitemap
|
||||||
Generates the ``sitemap.xml`` file.
|
Generates the ``sitemap.xml`` file.
|
||||||
|
|
||||||
@ -26,14 +19,6 @@ bin
|
|||||||
os_doc_tools directory
|
os_doc_tools directory
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
openstack-autohelp
|
|
||||||
A helper script run from the git repository by ``autogenerate_config_docs``.
|
|
||||||
|
|
||||||
openstack-auto-commands
|
|
||||||
Generates the command-line interface reference published at
|
|
||||||
https://docs.openstack.org/cli-reference/. A helper script to use this
|
|
||||||
tool is available at ``bin/doc-tools-update-cli-reference``.
|
|
||||||
|
|
||||||
openstack-jsoncheck
|
openstack-jsoncheck
|
||||||
Checks JSON files. Used for the API guides.
|
Checks JSON files. Used for the API guides.
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user