openstack-manuals/doc/contributor-guide/source/project-install-guide.rst

Installation tutorials and guides

For the Newton release, a new method of publishing installation tutorials and guides is being implemented. This will allow each big tent project to create their own installation guide, based on a standard template, in their own repository. These guides are then centrally published to docs.openstack.org.

For updates on the progress of this project, see the Install Guide wiki page. If you would like to help out, attend a meeting.

Set up project specific installation guides:

1. Install cookiecutter:

   # pip install cookiecutter

2. Run the Install Guide cookiecutter to create a skeleton for your project:

   $ cookiecutter https://git.openstack.org/openstack/installguide-cookiecutter.git

   You will be prompted to answer questions to complete the installation. Content will be added to the install-guide directory in the top-level of the project repository.

3. Create a tox.ini environment for install-guide in your project repository, using this content:

   [testenv:install-guide]
   commands = sphinx-build -a -E -W -d install-guide/build/doctrees -b html install-guide/source install-guide/build/html

4. Add your installation content, and test the build locally with tox:

   $ tox -e install-guide

   The local build is in install-guide/build/html.

5. Add the python package openstackdocstheme to the test-requirements.txt file. Copy the exact requirement line from the global file:

   openstackdocstheme>=1.5.0  # Apache-2.0

6. Commit the changes to your project repository for review.

After these changes have merged, you can set up the jobs for building.

1. Clone the project-config repo:

   $ git clone https://git.openstack.org/openstack-infra/project-config

2. In jenkins/jobs/projects.yaml, add install-guide-jobs within the entry for your project:

   - project:
       name: heat
       tarball-site: tarballs.openstack.org
       doc-publisher-site: docs.openstack.org
   
       jobs:
       ...
        - install-guide-jobs:
            service: orchestration

   Here service is the service name of the project, like orchestration for heat.

   This defines the jobs using the JJB install-guide-jobs job-template.

3. In zuul/layout.yaml, locate the entry for your project and add the install-guide-jobs template:

   - name: openstack/heat
     template:
       - name: install-guide-jobs

   This schedules the Install Guide jobs.

4. Commit the changes to the infra repository for review.

To create or update the master index file, create or update the www/project-install-guide/RELEASE/index.html file at the openstack-manuals repository. For draft (unreleased) version, replace RELEASE with draft.