diff --git a/doc/doc-contrib-guide/source/doc-tools.rst b/doc/doc-contrib-guide/source/doc-tools.rst index e4cd83add1..33d4fe8337 100644 --- a/doc/doc-contrib-guide/source/doc-tools.rst +++ b/doc/doc-contrib-guide/source/doc-tools.rst @@ -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 diff --git a/doc/doc-contrib-guide/source/doc-tools/cli-reference.rst b/doc/doc-contrib-guide/source/doc-tools/cli-reference.rst deleted file mode 100644 index ddb28ca187..0000000000 --- a/doc/doc-contrib-guide/source/doc-tools/cli-reference.rst +++ /dev/null @@ -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 `_ -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 - $ 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>`. diff --git a/doc/doc-contrib-guide/source/doc-tools/config-reference.rst b/doc/doc-contrib-guide/source/doc-tools/config-reference.rst deleted file mode 100644 index ec58c3c27a..0000000000 --- a/doc/doc-contrib-guide/source/doc-tools/config-reference.rst +++ /dev/null @@ -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 - `__. - -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 `_ -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 diff --git a/doc/doc-contrib-guide/source/doc-tools/scripts.rst b/doc/doc-contrib-guide/source/doc-tools/scripts.rst index 0f002472a3..bd4508aa6d 100644 --- a/doc/doc-contrib-guide/source/doc-tools/scripts.rst +++ b/doc/doc-contrib-guide/source/doc-tools/scripts.rst @@ -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.