[contrib-guide] Remove references to removed files
A number of tools and scripts in openstack-doc-tools have been removed. Remove the documentation for these too. Change-Id: I11917e603ccb7d30c7d44d17b8c5eccbe574b35c Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
This commit is contained in:
Stephen Finucane
parent
16ed92c767
commit
0bb20e83b8
|
|
@ -18,6 +18,4 @@ location, explains how to install, configure, use, and contribute to them.
|
|||
doc-tools/scripts.rst
|
||||
doc-tools/template-generator.rst
|
||||
doc-tools/installation.rst
|
||||
doc-tools/cli-reference.rst
|
||||
doc-tools/config-reference.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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
autogenerate_config_docs
|
||||
Generates configuration references published at
|
||||
https://docs.openstack.org/ocata/config-reference/.
|
||||
|
||||
cleanup directory
|
||||
Manually cleans up documentation files.
|
||||
|
||||
sitemap
|
||||
Generates the ``sitemap.xml`` file.
|
||||
|
||||
|
|
@ -26,14 +19,6 @@ bin
|
|||
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
|
||||
Checks JSON files. Used for the API guides.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue