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.
doc/source/
– Primary Ironic documentationapi-ref/source/
– API Reference (https://docs.openstack.org/api-ref/baremetal/)releasenotes/
– Release notes for Ironic
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.