1.. _community_documentation_contributions: 2 3***************************************** 4Contributing to the Ansible Documentation 5***************************************** 6 7Ansible has a lot of documentation and a small team of writers. Community support helps us keep up with new features, fixes, and changes. 8 9Improving the documentation is an easy way to make your first contribution to the Ansible project. You do not have to be a programmer, since most of our documentation is written in YAML (module documentation) or `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ (rST). Some collection-level documentation is written in a subset of `Markdown <https://github.com/ansible/ansible/issues/68119#issuecomment-596723053>`_. If you are using Ansible, you already use YAML in your playbooks. rST and Markdown are mostly just text. You do not even need git experience, if you use the ``Edit on GitHub`` option. 10 11If you find a typo, a broken example, a missing topic, or any other error or omission on this documentation website, let us know. Here are some ways to support Ansible documentation: 12 13.. contents:: 14 :local: 15 16Editing docs directly on GitHub 17=============================== 18 19For typos and other quick fixes, you can edit most of the documentation right from the site. Look at the top right corner of this page. That ``Edit on GitHub`` link is available on all the guide pages in the documentation. If you have a GitHub account, you can submit a quick and easy pull request this way. 20 21.. note:: 22 23 The source files for individual collection plugins exist in their respective repositories. Follow the link to the collection on Galaxy to find where the repository is located and any guidelines on how to contribute to that collection. 24 25To submit a documentation PR from docs.ansible.com with ``Edit on GitHub``: 26 27#. Click on ``Edit on GitHub``. 28#. If you don't already have a fork of the ansible repo on your GitHub account, you'll be prompted to create one. 29#. Fix the typo, update the example, or make whatever other change you have in mind. 30#. Enter a commit message in the first rectangle under the heading ``Propose file change`` at the bottom of the GitHub page. The more specific, the better. For example, "fixes typo in my_module description". You can put more detail in the second rectangle if you like. Leave the ``+label: docsite_pr`` there. 31#. Submit the suggested change by clicking on the green "Propose file change" button. GitHub will handle branching and committing for you, and open a page with the heading "Comparing Changes". 32#. Click on ``Create pull request`` to open the PR template. 33#. Fill out the PR template, including as much detail as appropriate for your change. You can change the title of your PR if you like (by default it's the same as your commit message). In the ``Issue Type`` section, delete all lines except the ``Docs Pull Request`` line. 34#. Submit your change by clicking on ``Create pull request`` button. 35#. Be patient while Ansibot, our automated script, adds labels, pings the docs maintainers, and kicks off a CI testing run. 36#. Keep an eye on your PR - the docs team may ask you for changes. 37 38Reviewing open PRs and issues 39============================= 40 41You can also contribute by reviewing open documentation `issues <https://github.com/ansible/ansible/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Adocs>`_ and `PRs <https://github.com/ansible/ansible/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3Adocs>`_. To add a helpful review, please: 42 43- Include a comment - "looks good to me" only helps if we know why. 44- For issues, reproduce the problem. 45- For PRs, test the change. 46 47Opening a new issue and/or PR 48============================= 49 50If the problem you have noticed is too complex to fix with the ``Edit on GitHub`` option, and no open issue or PR already documents the problem, please open an issue and/or a PR on the correct underlying repo - ``ansible/ansible`` for most pages that are not plugin or module documentation. If the documentation page has no ``Edit on GitHub`` option, check if the page is for a module within a collection. If so, follow the link to the collection on Galaxy and select the ``repo`` button in the upper right corner to find the source repository for that collection and module. The Collection README file should contain information on how to contribute to that collection, or report issues. 51 52A great documentation GitHub issue or PR includes: 53 54- a specific title 55- a detailed description of the problem (even for a PR - it's hard to evaluate a suggested change unless we know what problem it's meant to solve) 56- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on) 57 58 59Verifying your documentation PR 60================================ 61 62If you make multiple changes to the documentation on ``ansible/ansible``, or add more than a line to it, before you open a pull request, please: 63 64#. Check that your text follows our :ref:`style_guide`. 65#. Test your changes for rST errors. 66#. Build the page, and preferably the entire documentation site, locally. 67 68.. note:: 69 70 The following sections apply to documentation sourced from the ``ansible/ansible`` repo and does not apply to documentation from an individual collection. See the collection README file for details on how to contribute to that collection. 71 72Setting up your environment to build documentation locally 73---------------------------------------------------------- 74 75To build documentation locally, ensure you have a working :ref:`development environment <environment_setup>`. 76 77To work with documentation on your local machine, you need to have python-3.5 or greater and install the `Ansible dependencies`_ and `documentation dependencies`_, which are listed in two :file:`requirements.txt` files to make installation easier: 78 79.. _Ansible dependencies: https://github.com/ansible/ansible/blob/devel/requirements.txt 80.. _documentation dependencies: https://github.com/ansible/ansible/blob/devel/docs/docsite/requirements.txt 81 82.. code-block:: bash 83 84 pip install --user -r requirements.txt 85 pip install --user -r docs/docsite/requirements.txt 86 87The :file:`docs/docsite/requirements.txt` file allows a wide range of versions and may install new releases of required packages. New releases of these packages may cause problems with the Ansible docs build. If you want to install tested versions of these dependencies, use :file:`docs/docsite/known_good_reqs.txt` instead: 88 89.. code-block:: bash 90 91 pip install --user -r requirements.txt 92 pip install --user -r docs/docsite/known_good_reqs.txt 93 94You can drop ``--user`` if you have set up a virtual environment (venv/virtenv). 95 96.. note:: 97 98 You may need to install these general pre-requisites separately on some systems: 99 - ``gcc`` 100 - ``libyaml`` 101 - ``make`` 102 - ``pyparsing`` 103 - ``six`` 104 On macOS with Xcode, you may need to install ``six`` and ``pyparsing`` with ``--ignore-installed`` to get versions that work with ``sphinx``. 105 106.. note:: 107 108 After checking out ``ansible/ansible``, make sure the ``docs/docsite/rst`` directory has strict enough permissions. It should only be writable by the owner's account. If your default ``umask`` is not 022, you can use ``chmod go-w docs/docsite/rst`` to set the permissions correctly in your new branch. Optionally, you can set your ``umask`` to 022 to make all newly created files on your system (including those created by ``git clone``) have the correct permissions. 109 110.. _testing_documentation_locally: 111 112Testing the documentation locally 113--------------------------------- 114 115To test an individual file for rST errors: 116 117.. code-block:: bash 118 119 rstcheck changed_file.rst 120 121Building the documentation locally 122---------------------------------- 123 124Building the documentation is the best way to check for errors and review your changes. Once `rstcheck` runs with no errors, navigate to ``ansible/docs/docsite`` and then build the page(s) you want to review. 125 126Building a single rST page 127^^^^^^^^^^^^^^^^^^^^^^^^^^ 128 129To build a single rST file with the make utility: 130 131.. code-block:: bash 132 133 make htmlsingle rst=path/to/your_file.rst 134 135For example: 136 137.. code-block:: bash 138 139 make htmlsingle rst=community/documentation_contributions.rst 140 141This process compiles all the links but provides minimal log output. If you're writing a new page or want more detailed log output, refer to the instructions on :ref:`build_with_sphinx-build` 142 143.. note:: 144 145 ``make htmlsingle`` adds ``rst/`` to the beginning of the path you provide in ``rst=``, so you can't type the filename with autocomplete. Here are the error messages you will see if you get this wrong: 146 147 - If you run ``make htmlsingle`` from the ``docs/docsite/rst/`` directory: ``make: *** No rule to make target `htmlsingle'. Stop.`` 148 - If you run ``make htmlsingle`` from the ``docs/docsite/`` directory with the full path to your rST document: ``sphinx-build: error: cannot find files ['rst/rst/community/documentation_contributions.rst']``. 149 150 151Building all the rST pages 152^^^^^^^^^^^^^^^^^^^^^^^^^^ 153 154To build all the rST files without any module documentation: 155 156.. code-block:: bash 157 158 MODULES=none make webdocs 159 160Building module docs and rST pages 161^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 162 163To build documentation for a few modules included in ``ansible/ansible`` plus all the rST files, use a comma-separated list: 164 165.. code-block:: bash 166 167 MODULES=one_module,another_module make webdocs 168 169To build all the module documentation plus all the rST files: 170 171.. code-block:: bash 172 173 make webdocs 174 175.. _build_with_sphinx-build: 176 177Building rST files with ``sphinx-build`` 178^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 179 180Advanced users can build one or more rST files with the sphinx utility directly. ``sphinx-build`` returns misleading ``undefined label`` warnings if you only build a single page, because it does not create internal links. However, ``sphinx-build`` returns more extensive syntax feedback, including warnings about indentation errors and ``x-string without end-string`` warnings. This can be useful, especially if you're creating a new page from scratch. To build a page or pages with ``sphinx-build``: 181 182.. code-block:: bash 183 184 sphinx-build [options] sourcedir outdir [filenames...] 185 186You can specify filenames, or ``–a`` for all files, or omit both to compile only new/changed files. 187 188For example: 189 190.. code-block:: bash 191 192 sphinx-build -b html -c rst/ rst/dev_guide/ _build/html/dev_guide/ rst/dev_guide/developing_modules_documenting.rst 193 194Running the final tests 195^^^^^^^^^^^^^^^^^^^^^^^ 196 197When you submit a documentation pull request, automated tests are run. Those same tests can be run locally. To do so, navigate to the repository's top directory and run: 198 199.. code-block:: bash 200 201 make clean && 202 bin/ansible-test sanity --test docs-build && 203 bin/ansible-test sanity --test rstcheck 204 205Unfortunately, leftover rST-files from previous document-generating can occasionally confuse these tests. It is therefore safest to run them on a clean copy of the repository, which is the purpose of ``make clean``. If you type these three lines one at a time and manually check the success of each, you do not need the ``&&``. 206 207Joining the documentation working group 208======================================= 209 210The Documentation Working Group (DaWGs) meets weekly on Tuesdays on the #ansible-docs channel on the `libera.chat IRC network <https://libera.chat/>`_. For more information, including links to our agenda and a calendar invite, please visit the `working group page in the community repo <https://github.com/ansible/community/wiki/Docs>`_. 211 212.. seealso:: 213 :ref:`More about testing module documentation <testing_module_documentation>` 214 215 :ref:`More about documenting modules <module_documenting>` 216