Update the instructions to indicate which guides are no longer maintained by the docs team and how those docs are handled instead. Explain the data input to the www-generator.py tool Update the release instructions to explain how to update the templated portion of the site. Change-Id: I08bb228a6807bfcee0a6ab72ddaf229b455c9d1d Signed-off-by: Doug Hellmann <doug@doughellmann.com>
2.7 KiB
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
- autogenerate_config_docs
-
Generates configuration references published at https://docs.openstack.org/ocata/config-reference/.
- build_environment directory (deprecated)
-
A Vagrant environment for working with the guides.
- cleanup directory
-
Manually cleans up documentation files.
- sitemap
-
Generates the
sitemap.xml
file. - bin
-
Contains scripts for building documents in the
openstack-manuals
repository. Used inside the tox environments.
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.
openstack-manuals repository
Several scripts currently reside in the openstack-manuals
repository. It may be beneficial to consolidate these into the
openstack-doc-tools
repository.
- www-generator.py
-
Generates static, template-based HTML files for https://docs.openstack.org/. The script reads YAML data files in
www/project-data
to determine which projects exist in a given series and how they should be displayed on the list of installation, configuration, and other guides. The filewww/project-data/schema.yaml
contains the JSONSchema settings to describe what a valid data file looks like. - sync-projects.sh
-
Synchronizes the Glossary, common files, and some translations across multiple repositories, including
api-site
andsecurity-doc
. - publishdocs.sh
-
Publishdocs job uses this script to publish documentation to https://docs.openstack.org/.
Notes
openstack-doc-tools
must be released so it can be pinned in requirements files, enabling automation to work across repositories.- There are many undocumented synchronizations (automated and manual) between the various documentation repositories. These should be documented.
- There are a several jobs that must be run regularly, for example,
updating the
sitemap.xml
file and the command line configuration reference. These should be documented. - Some manual jobs should be automated. For example, the
sitemap.xml
file should be automatically updated by the Gerritbot.