Contributing to Ironic Docs

This guide will help you get started with contributing to Ironic docs, whether you are fixing a typo or writing a new section.

Where the Docs Live

Ironic has multiple documentation sources located in different directories of the openstack/ironic repository.

How to Get Started

Clone the repository locally and create a new branch for your work.

For setup instructions, including creating a Gerrit account refer to the Developer’s Guide.

Make and Preview Documentation Changes

You can preview your documentation changes locally using the following command:

tox -e docs

This will build the HTML version in doc/build/html/. Open index.html in your browser to view your updates.

Note

If you have created a new file, make sure to include its path in the documentation table of contents.

To do this, edit doc/source/index.rst (or another relevant .rst file) and add the relative path of your new file to the .. toctree:: directive. For example:

.. toctree::
   :maxdepth: 2

   contributor/doc_contributing

To open the generated HTML:

Option 1 – Open the HTML file directly:

  • On Linux:

xdg-open doc/build/html/index.html

  • On macOS:

open doc/build/html/index.html

  • On Windows:

Navigate to the doc/build/html/ folder and double-click index.html.

Option 2 – Start a local web server (Cross-platform):

cd doc/build/html
python -m http.server

Then navigate to URL.

Lint and Check Your Work

Before submitting, check your documentation and code formatting with:

tox -e pep8

This ensures .rst files follow style guidelines and catch common mistakes.

How to Submit Your Changes

After confirming your changes are correct, commit them with a clear message and submit for review with:

git review

Your patch will appear in the OpenStack Gerrit system for feedback and approval.

Writing Style and Guidelines

  • Follow OpenStack’s documentation style guide.

  • Keep language clear, inclusive, and technical.

  • Avoid passive voice and ambiguous words.

  • Use reStructuredText (.rst) syntax.

Asking for Help

If you are stuck, don’t hesitate to reach out to the ironic community.

Maintainers and review team information can be found in the doc/OWNERS file.