8ce45e7155
This patch improves the contributor documentation by: - Listing all documentation sources used in Ironic - Adding cross-platform instructions to preview built documentation These updates make the documentation-contributing guide more accurate and accessible for contributors. Partial-Bug: #2072364 Change-Id: Icd0bf1188cf0b276ee278a78c1c58dd70c55f232
116 lines
3.1 KiB
ReStructuredText
116 lines
3.1 KiB
ReStructuredText
===============================
|
||
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 <https://opendev.org/openstack/ironic>`_.
|
||
|
||
- ``doc/source/`` – Primary Ironic documentation
|
||
- ``api-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 <https://docs.opendev.org/opendev/infra-manual/latest/developers.html>`_.
|
||
|
||
Make and Preview Documentation Changes
|
||
----------------------------------------
|
||
|
||
You can preview your documentation changes locally using the following command:
|
||
|
||
.. code-block:: bash
|
||
|
||
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:
|
||
|
||
.. code-block:: rst
|
||
|
||
.. toctree::
|
||
:maxdepth: 2
|
||
|
||
contributor/doc_contributing
|
||
|
||
To open the generated HTML:
|
||
|
||
**Option 1 – Open the HTML file directly:**
|
||
|
||
- On Linux:
|
||
|
||
.. code-block:: bash
|
||
|
||
xdg-open doc/build/html/index.html
|
||
|
||
- On macOS:
|
||
|
||
.. code-block:: bash
|
||
|
||
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):**
|
||
|
||
.. code-block:: bash
|
||
|
||
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:
|
||
|
||
.. code-block:: bash
|
||
|
||
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:
|
||
|
||
.. code-block:: bash
|
||
|
||
git review
|
||
|
||
Your patch will appear in the OpenStack Gerrit system for feedback and approval.
|
||
|
||
Writing Style and Guidelines
|
||
-----------------------------
|
||
|
||
* Follow OpenStack's `documentation <https://docs.openstack.org/doc-contrib-guide/>`_ 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 <https://docs.openstack.org/ironic/latest/contributor/community.html>`_.
|
||
|
||
|
||
Maintainers and review team information can be found in the ``doc/OWNERS`` file.
|