ansible/docs/docsite/rst/community/documentation_contributions.rst

215 lines
11 KiB
ReStructuredText
Raw Normal View History

.. _community_documentation_contributions:
*****************************************
Contributing to the Ansible Documentation
*****************************************
Ansible has a lot of documentation and a small team of writers. Community support helps us keep up with new features, fixes, and changes.
Improving the documentation is an easy way to make your first contribution to the Ansible project. You don't have to be a programmer, since most of our documentation is written in YAML (module documentation) or `reStructuredText <http://docutils.sourceforge.net/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're using Ansible, you already use YAML in your playbooks. rST and Markdown are mostly just text. You don't even need git experience, if you use the ``Edit on GitHub`` option.
If 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:
.. contents::
:local:
Editing docs directly on GitHub
===============================
For 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.
.. note::
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.
To submit a documentation PR from docs.ansible.com with ``Edit on GitHub``:
#. Click on ``Edit on GitHub``.
#. If you don't already have a fork of the ansible repo on your GitHub account, you'll be prompted to create one.
#. Fix the typo, update the example, or make whatever other change you have in mind.
#. 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.
#. 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".
#. Click on ``Create pull request`` to open the PR template.
#. 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.
#. Submit your change by clicking on ``Create pull request`` button.
#. Be patient while Ansibot, our automated script, adds labels, pings the docs maintainers, and kicks off a CI testing run.
#. Keep an eye on your PR - the docs team may ask you for changes.
Reviewing open PRs and issues
=============================
You 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:
- Include a comment - "looks good to me" only helps if we know why.
- For issues, reproduce the problem.
- For PRs, test the change.
Opening a new issue and/or PR
=============================
If the problem you've 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 ``ansible/ansible`` repo. 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.
A great documentation GitHub issue or PR includes:
- a specific title
- 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)
- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on.)
Verifying your documentation PR
================================
If 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:
#. Check that your text follows our :ref:`style_guide`.
#. Test your changes for rST errors.
#. Build the page, and preferably the entire documentation site, locally.
.. note::
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.
Setting up your environment to build documentation locally
----------------------------------------------------------
To build documentation locally, ensure you have a working :ref:`development environment <environment_setup>`.
To work with documentation on your local machine, you need to have python-3.5 or greater and the
following packages installed:
- gcc
- jinja2
- libyaml
- Pygments >= 2.4.0
- pyparsing
- PyYAML
- rstcheck
- six
- sphinx
- sphinx-notfound-page
- straight.plugin
These required packages are listed in two :file:`requirements.txt` files to make installation easier:
.. code-block:: bash
pip install --user -r requirements.txt
pip install --user -r docs/docsite/requirements.txt
2020-02-21 11:57:07 +01:00
You can drop ``--user`` if you have set up a virtual environment (venv/virtenv).
.. note::
On macOS with Xcode, you may need to install ``six`` and ``pyparsing`` with ``--ignore-installed`` to get versions that work with ``sphinx``.
Docs backportapalooza 4 (#70875) * Pipe lookup plugin usage example documentation fix (#70679) (cherry picked from commit 58d24584c0c5a60b8193df62e24477c8cc6edc7d) * Fix misleading documentation for naming blocks (#68458) From what I have observed it is the block itself that doesn't support the name attribute rather than the tasks inside the block. * Update docs/docsite/rst/user_guide/playbooks_blocks.rst Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> (cherry picked from commit 633c2d052249703016cd3938e6bad9877fc8d189) * Fix incorrect statement to set a variable for a playbook (#70712) Fixes #70638 (cherry picked from commit 59513ae673a52675ca8f8f47e85af21b905566fd) * Make Sources, Plugins sections easier to read (#70652) Re-wrote the Inventory Sources section and also the next section to have shorter, clearer sentences with a more active voice. (cherry picked from commit fb3db170cc98279e2c7d941abdb01e2bbf96222b) * fix rstcheck problem and gitignore collections dir (#70764) (cherry picked from commit 24e5d3a51cf11586cb20b76c71350757f38f7bb3) * add note for write permission on rst files (#70766) * add note for write permission on rst files * Update docs/docsite/rst/community/documentation_contributions.rst Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> (cherry picked from commit 2a7df5e07b4d6479580803e12e4bd182509fd90e) * Modification of 'Adding modules and plugins locally' topic (#70659) * Remediated the topic to comply with IBM style guide and minimalism practices Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> (cherry picked from commit 17332532973343248297e3d3c746738d1f3b2f56) * WIP: add collections as an intersphinx link (#70826) * adds collections as a ref for intersphinx * no need for intersphinx Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com> (cherry picked from commit b28d59124b679bc3221589793440cc90cddc9b45) * Proper example for splitext filter in docs (#70494) * Update playbooks_filters.rst with a clear example of how to extract its 2 tokens. Co-authored-by: Sloane Hertel <shertel@redhat.com> (cherry picked from commit 7a42d2746200e560fa42edfe3a4e031f21411e38) * Few fixes for reference_appendices/faq.html (#70719) * Format using `` instead of `, add line breaks for long lines, rephrase or remove useless text. Move some text. * Add clearer version of OpenSSh is affected by SCP bug * Review some pages using ansible doc writing guide. (cherry picked from commit 92e16c2838182f58f2cedf25ca19273159d2246d) Co-authored-by: Roman Gorshunov <34521622+gorshunovr@users.noreply.github.com> Co-authored-by: David Rieger <david@isan.engineer> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Stef B <regendo@users.noreply.github.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Fixmetal <fixmetal@gmail.com>
2020-07-29 00:38:17 +02:00
.. note::
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.
.. _testing_documentation_locally:
Testing the documentation locally
---------------------------------
To test an individual file for rST errors:
.. code-block:: bash
rstcheck changed_file.rst
Building the documentation locally
----------------------------------
Building 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.
Building a single rST page
^^^^^^^^^^^^^^^^^^^^^^^^^^
To build a single rST file with the make utility:
.. code-block:: bash
make htmlsingle rst=path/to/your_file.rst
For example:
.. code-block:: bash
make htmlsingle rst=community/documentation_contributions.rst
This 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`
.. note::
``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:
- If you run ``make htmlsingle`` from the ``docs/docsite/rst/`` directory: ``make: *** No rule to make target `htmlsingle'. Stop.``
- 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']``.
Building all the rST pages
^^^^^^^^^^^^^^^^^^^^^^^^^^
To build all the rST files without any module documentation:
.. code-block:: bash
MODULES=none make webdocs
Building module docs and rST pages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To build documentation for a few modules included in ``ansible/ansible`` plus all the rST files, use a comma-separated list:
.. code-block:: bash
MODULES=one_module,another_module make webdocs
To build all the module documentation plus all the rST files:
.. code-block:: bash
make webdocs
.. _build_with_sphinx-build:
Building rST files with ``sphinx-build``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Advanced 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``:
.. code-block:: bash
sphinx-build [options] sourcedir outdir [filenames...]
You can specify filenames, or ``a`` for all files, or omit both to compile only new/changed files.
For example:
.. code-block:: bash
sphinx-build -b html -c rst/ rst/dev_guide/ _build/html/dev_guide/ rst/dev_guide/developing_modules_documenting.rst
Running the final tests
^^^^^^^^^^^^^^^^^^^^^^^
When 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:
.. code-block:: bash
make clean &&
bin/ansible-test sanity --test docs-build &&
bin/ansible-test sanity --test rstcheck
Unfortunately, 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 ``&&``.
Joining the documentation working group
=======================================
The Documentation Working Group is just getting started, please visit the `community repo <https://github.com/ansible/community>`_ for more information.
.. seealso::
:ref:`More about testing module documentation <testing_module_documentation>`
:ref:`More about documenting modules <module_documenting>`