Merge "doc: Update contributor docs to include multiple doc sources and preview options"

doc/source/contributor/documentation-contributing.rst

@@ -0,0 +1,115 @@
+===============================
+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.

doc/source/index.rst

@@ -99,6 +99,11 @@ Contributor Guide
 
    contributor/index
 
+.. toctree::
+   :maxdepth: 3
+
+   contributor/documentation-contributing
+
 Support Resources
 =================