-
Notifications
You must be signed in to change notification settings - Fork 23.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add docs about contributing to docs #46481
Merged
Merged
Changes from all commits
Commits
Show all changes
19 commits
Select commit
Hold shift + click to select a range
ff4c2b3
adds page on community contributions to docs
acozine d151261
adds new page to community TOC
acozine bbbcf2f
expands, adds info on docs build and testing
acozine b8c1c26
refine the docs contrib page
acozine 3c46be9
adds anchor for style guide index
acozine 8d2e95f
more revisions
acozine 82f8b56
adds note about macOS packages, plus
acozine 26460f2
refinements
acozine f039764
tidying
acozine caf4ee4
adds link to community repo
acozine 17f7e24
adds pointer about build errors
acozine b2c44f5
no smart quotes, stop pasting from Word docs
acozine 1b5dc75
incorporate cbudz feedback
acozine d219b2f
added missing backtick
acozine 47e3ba3
incorporates gundalow feedback
acozine fbba545
adds link from dev_guide to community page for docs testing
acozine f4d8ead
add bulleted list within note, fix links
acozine d6dfe15
fix broken links
acozine 8db015b
incorporates samccann feedback
acozine File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
173 changes: 173 additions & 0 deletions
173
docs/docsite/rst/community/documentation_contributions.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,173 @@ | ||
.. _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 our documentation is written in YAML (module documentation) or `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ (rST). If you're using Ansible, you already use YAML in your playbooks. And rST is 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 the documentation right from the site. Look at the top right corner of this page. That ``Edit on GitHub`` link is available on every page in the documentation. If you have a GitHub account, you can submit a quick and easy pull request this way. | ||
|
||
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: | ||
|
||
acozine marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- 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. | ||
|
||
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, etc.) | ||
|
||
Before you open a complex documentation PR | ||
========================================== | ||
|
||
If you make multiple changes to the documentation, 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. | ||
|
||
To work with documentation on your local machine, you need the following packages installed: | ||
|
||
.. code-block:: none | ||
|
||
- libyaml | ||
- pyyaml | ||
- nose | ||
- six | ||
- tornado | ||
- pyparsing | ||
- gcc | ||
- jinja2 | ||
- rstcheck | ||
- sphinx | ||
|
||
.. note:: | ||
|
||
On macOS with Xcode, you may need to install ``six`` and ``pyparsing`` with ``--ignore-installed`` to get versions that work wth ``sphinx``. | ||
|
||
.. _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 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 | ||
|
||
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>` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -28,6 +28,11 @@ There are many forums online where Ansible users ask and answer questions. Reach | |||||
|
||||||
You can find the official :ref:`Ansible communication channels <communication>`. | ||||||
|
||||||
Review, fix, and maintain the documentation | ||||||
=========================================== | ||||||
|
||||||
Typos are everywhere, even in the Ansible documentation. We work hard to keep the documentation up-to-date, but you may also find out-dated examples. We offer easy ways to :ref:`report and/or fix documentation errors <community_documentation_contributions>`. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. "out-dated" should be "outdated" instead.
Suggested change
|
||||||
|
||||||
Participate in your local meetup | ||||||
================================ | ||||||
|
||||||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should Module DOCUMENTATION in dev_guide link to this?