Deployment guides¶
As of the Newton release, a new method of publishing deployment guides has been implemented. This allows each deployment projects to create their own deployment guide, based on a standard template, in their own repository. These guides are then centrally published to Deployment Guides.
Note
This set up is designed for deployment projects to make their installation information public. This does not include further content for end users. For example, configuration content, troubleshooting, or administration procedures.
If you would like to refer users to more content, use cross reference links to your developer documentation within the guide.
Setting up¶
Install
cookiecutter
:# pip install cookiecutter
Run the Install Guide cookiecutter to create a skeleton for your project:
Important
The Install Guide cookiecutter is also used for the deployment guides. However, the rest of these instructions are specific to the deployment guide creation.
$ cookiecutter https://opendev.org/openstack/installguide-cookiecutter.git --checkout HEAD^1
You will be prompted to answer questions to complete the installation. Content is then added to the
deploy-guide
directory in the top-level of the project repository.Create a
tox.ini
environment for thedeploy-guide
in your project repository, using this content:[testenv:deploy-guide] whitelist_externals = rm commands = rm -rf deploy-guide/build sphinx-build -a -E -W -d deploy-guide/build/doctrees -b html deploy-guide/source deploy-guide/build/html
Add your deployment guide content, and test the build locally with
tox
:$ tox -e deploy-guide
The local build is in
deploy-guide/build/html
.Add the Python package
openstackdocstheme
to thetest-requirements.txt
file. Copy the exact requirement line from the global file:openstackdocstheme>=1.5.0 # Apache-2.0
Commit the changes to your project repository for review.
After these changes merge, you can set up the jobs for building in the
OpenStack Infra project-config
repository:
Clone the project-config repo:
$ git clone https://opendev.org/openstack/project-config
In
jenkins/jobs/projects.yaml
, adddeploy-guide-jobs
within the entry for your project:- project: name: <project-name> jobs: ... - deploy-guide-jobs: service: <service-name>
project-name
andservice-name
are the project name, and the specific service name. One example is orchestration for heat.This defines the jobs using the JJB
deploy-guide-jobs
job-template.In
zuul/layout.yaml
, locate the entry for your project and add thedeploy-guide-jobs
template:- name: openstack/<project-name> template: - name: deploy-guide-jobs
This schedules the Deploy Guide jobs.
Commit the changes to the infra repository for review.
To update the main index pages with a link to your deployment guide, see Template generator details.
Deployment guide and installation guide links¶
If you have links between your deployment guide or installation guide and your normal documents, you need to take extra care that the links work. Any links to your old installation guide will now point to nothing.
We recommend adding conditional branch names for documentation links within your repo. Documents generated this way will always point to the live URLs, not to HTML, generated for a gate job.
The link generation is done via the sphinx.ext.extlinks
extension, allowing for defining custom link generation roles. This
achieves the desired behavior in terms of dynamic link construction, but
does alter the standard linking conventions.
Usage for the deploy guide is as follows:
:deploy_guide:`Link title text <last-part-of-url.html>`
For an example, and more information, please review the following OpenStack-Ansible patch: Add conditional branch names for docs links