Add docs about contributing to docs #46481

acozine · 2018-10-04T14:03:08Z

SUMMARY

Offers guidance for community members who want to contribute to the documentation.

Based on the AnsibleFest talk from 2018.

ISSUE TYPE

Docs Pull Request

COMPONENT NAME

docs.ansible.com

ANSIBLE VERSION

2.8

ansibot · 2018-10-04T14:12:49Z

The test ansible-test sanity --test no-smart-quotes [explain] failed with 1 error:

docs/docsite/rst/community/documentation_contributions.rst:118:39: use ASCII quotes `'` and `"` instead of Unicode quotes

The test ansible-test sanity --test rstcheck [explain] failed with 2 errors:

docs/docsite/rst/community/documentation_contributions.rst:93:0: (bash) `make htmlsingle rst=<relative/path/to/your_file.rst>'
docs/docsite/rst/community/documentation_contributions.rst:93:0: (bash) syntax error near unexpected token `newline'

click here for bot help

remyleone · 2018-10-08T16:12:12Z

docs/docsite/rst/community/documentation_contributions.rst

+
+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 reStructured Text. If you're using Ansible, you know YAML - playbooks are written in YAML. 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 docs.ansible.com, let us know. Here are some ways to support Ansible documentation:


Could it be a link?

remyleone · 2018-10-08T16:14:00Z

docs/docsite/rst/community/documentation_contributions.rst

+Joining the documentation working group
+=======================================
+
+The Documentation Working Group is just getting started, please visit the community repo for more information.


Where is located this community repo?

acozine · 2018-10-18T20:44:42Z

Ready for review. The branch is published (temporarily) at http://docs.testing.ansible.com/ansible/latest/community/documentation_contributions.html#community-documentation-contributions and associated pages.

felixfontein · 2018-10-19T05:49:43Z

docs/docsite/rst/community/documentation_contributions.rst

+
+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 reStructured Text. If you're using Ansible, you know YAML - playbooks are written in YAML. And rST is mostly just text. You don't even need git experience, if you use the ``Edit on GitHub`` option.


Shouldn't it be YAML-playbooks or YAML playbooks, and not YAML - playbooks?

or reStructured Text
or reStructured Text (RST)

gundalow · 2018-10-19T07:52:32Z

docs/docsite/rst/community/documentation_contributions.rst

+
+    ``make htmlsingle`` adds ``rst/`` to the beginning of the path you provide in ``rst=``, so you can't type the filename with autocomplete. If you run ``make htmlsingle`` from the ``docs/docsite/rst/`` directory, you'll get ``make: *** No rule to make target `htmlsingle'.  Stop.`` If you run it from ``docs/docsite/`` and provide the full path, you'll get ``sphinx-build: error: cannot find files ['rst/rst/community/documentation_contributions.rst']``.
+
+2. Building an rST file with sphinx-build:


I wonder if you could his should be marked as advanced? I've never use it.

Maybe move to the end of the doc under and advanced section

gundalow · 2018-10-19T07:53:40Z

docs/docsite/rst/community/documentation_contributions.rst

+
+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 reStructured Text. If you're using Ansible, you know YAML - playbooks are written in YAML. And rST is mostly just text. You don't even need git experience, if you use the ``Edit on GitHub`` option.


or reStructured Text
or reStructured Text (RST)

gundalow · 2018-10-19T07:55:12Z

docs/docsite/rst/community/documentation_contributions.rst

@@ -0,0 +1,166 @@
+.. _community_documentation_contributions:


Should Module DOCUMENTATION in dev_guide link to this?

gundalow · 2018-10-19T07:56:44Z

docs/docsite/rst/community/documentation_contributions.rst

+
+.. note::
+
+    ``make htmlsingle`` adds ``rst/`` to the beginning of the path you provide in ``rst=``, so you can't type the filename with autocomplete. If you run ``make htmlsingle`` from the ``docs/docsite/rst/`` directory, you'll get ``make: *** No rule to make target `htmlsingle'.  Stop.`` If you run it from ``docs/docsite/`` and provide the full path, you'll get ``sphinx-build: error: cannot find files ['rst/rst/community/documentation_contributions.rst']``.


Can we break this into steps?

ansibot · 2018-10-23T18:35:43Z

The test ansible-test sanity --test docs-build [explain] failed with 1 error:

docs/docsite/rst/community/documentation_contributions.rst:120:0: warning: Bullet list ends without a blank line; unexpected unindent.

The test ansible-test sanity --test rstcheck [explain] failed with 1 error:

docs/docsite/rst/community/documentation_contributions.rst:120:0: Bullet list ends without a blank line; unexpected unindent.

click here for bot help

ansibot · 2018-10-23T18:45:50Z

The test ansible-test sanity --test docs-build [explain] failed with 3 errors:

docs/docsite/rst/community/documentation_contributions.rst:120:0: warning: Bullet list ends without a blank line; unexpected unindent.
docs/docsite/rst/community/documentation_contributions.rst:169:0: undefined-label: undefined label: testing_documentation (if the link has no caption the label must precede a section header)
docs/docsite/rst/dev_guide/developing_modules_documenting.rst:126:0: undefined-label: undefined label: testing_documentation (if the link has no caption the label must precede a section header)

The test ansible-test sanity --test rstcheck [explain] failed with 1 error:

docs/docsite/rst/community/documentation_contributions.rst:120:0: Bullet list ends without a blank line; unexpected unindent.

click here for bot help

samccann · 2018-10-23T20:13:48Z

docs/docsite/rst/community/documentation_contributions.rst

+
+   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:``


missing what :ref: is pointing to here?

Zeut alors, I have missed one!

docs/docsite/rst/community/documentation_contributions.rst

beeankha · 2018-10-24T00:39:45Z

docs/docsite/rst/community/how_can_I_help.rst

+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>`.


"out-dated" should be "outdated" instead.

Suggested change

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>`.

Typos are everywhere, even in the Ansible documentation. We work hard to keep the documentation up-to-date, but you may also find outdated examples. We offer easy ways to :ref:`report and/or fix documentation errors <community_documentation_contributions>`.

* adds page on community contributions to docs (cherry picked from commit 4219d25)

* adds page on community contributions to docs

samdoran removed the needs_triage Needs a first human triage before being processed. label Oct 4, 2018

acozine mentioned this pull request Oct 8, 2018

Where should we document that you can regenerate only one page? #45832

Closed

remyleone reviewed Oct 8, 2018

View reviewed changes

ansibot removed the ci_verified Changes made in this PR are causing tests to fail. label Oct 9, 2018

acozine removed the WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. label Oct 18, 2018

ansibot added the WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. label Oct 18, 2018

acozine changed the title ~~WIP: Contribute to docs~~ Add docs about contributing to docs Oct 18, 2018

acozine removed the WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. label Oct 18, 2018

acozine added this to To do in OLD Ansible Documentation via automation Oct 18, 2018

ansibot added the core_review In order to be merged, this PR must follow the core review workflow. label Oct 18, 2018

felixfontein reviewed Oct 19, 2018

View reviewed changes

gundalow reviewed Oct 19, 2018

View reviewed changes

acozine added 9 commits October 23, 2018 13:27

adds page on community contributions to docs

ff4c2b3

adds new page to community TOC

d151261

expands, adds info on docs build and testing

bbbcf2f

refine the docs contrib page

b8c1c26

adds anchor for style guide index

3c46be9

more revisions

8d2e95f

adds note about macOS packages, plus

82f8b56

refinements

26460f2

tidying

f039764

acozine added 5 commits October 23, 2018 13:27

adds pointer about build errors

17f7e24

no smart quotes, stop pasting from Word docs

b2c44f5

incorporate cbudz feedback

1b5dc75

added missing backtick

d219b2f

incorporates gundalow feedback

47e3ba3

ansibot added ci_verified Changes made in this PR are causing tests to fail. needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. and removed core_review In order to be merged, this PR must follow the core review workflow. labels Oct 23, 2018

adds link from dev_guide to community page for docs testing

fbba545

acozine force-pushed the contribute-to-docs branch from 72ebc76 to fbba545 Compare October 23, 2018 18:36

add bulleted list within note, fix links

f4d8ead

ansibot removed the ci_verified Changes made in this PR are causing tests to fail. label Oct 23, 2018

fix broken links

d6dfe15

ansibot added core_review In order to be merged, this PR must follow the core review workflow. and removed needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. labels Oct 23, 2018

gundalow approved these changes Oct 23, 2018

View reviewed changes

samccann reviewed Oct 23, 2018

View reviewed changes

incorporates samccann feedback

8db015b

samccann approved these changes Oct 24, 2018

View reviewed changes

samccann merged commit 4219d25 into ansible:devel Oct 24, 2018

beeankha reviewed Oct 24, 2018

View reviewed changes

gundalow pushed a commit to gundalow/ansible that referenced this pull request Oct 26, 2018

Add docs about contributing to docs (ansible#46481)

0697c5c

* adds page on community contributions to docs (cherry picked from commit 4219d25)

acozine pushed a commit that referenced this pull request Oct 26, 2018

Add docs about contributing to docs (#46481) (#47658)

6cfdd9f

* adds page on community contributions to docs (cherry picked from commit 4219d25)

acozine moved this from To do to Done in OLD Ansible Documentation Nov 7, 2018

acozine deleted the contribute-to-docs branch November 29, 2018 20:39

Tomorrow9 pushed a commit to Tomorrow9/ansible that referenced this pull request Dec 4, 2018

Add docs about contributing to docs (ansible#46481)

ae54ff2

* adds page on community contributions to docs

ansible locked and limited conversation to collaborators Jul 22, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs about contributing to docs #46481

Add docs about contributing to docs #46481

acozine commented Oct 4, 2018

ansibot commented Oct 4, 2018

remyleone Oct 8, 2018

remyleone Oct 8, 2018

acozine commented Oct 18, 2018

felixfontein Oct 19, 2018

gundalow Oct 19, 2018

gundalow Oct 19, 2018

gundalow Oct 19, 2018

gundalow Oct 19, 2018

gundalow Oct 19, 2018

ansibot commented Oct 23, 2018

ansibot commented Oct 23, 2018

samccann Oct 23, 2018

acozine Oct 23, 2018

beeankha Oct 24, 2018


		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 reStructured Text. If you're using Ansible, you know YAML - playbooks are written in YAML. 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 docs.ansible.com, let us know. Here are some ways to support 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 reStructured Text. If you're using Ansible, you know YAML - playbooks are written in YAML. And rST is mostly just text. You don't even need git experience, if you use the ``Edit on GitHub`` option.


		``make htmlsingle`` adds ``rst/`` to the beginning of the path you provide in ``rst=``, so you can't type the filename with autocomplete. If you run ``make htmlsingle`` from the ``docs/docsite/rst/`` directory, you'll get ``make: *** No rule to make target `htmlsingle'. Stop.`` If you run it from ``docs/docsite/`` and provide the full path, you'll get ``sphinx-build: error: cannot find files ['rst/rst/community/documentation_contributions.rst']``.

		2. Building an rST file 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. If you run ``make htmlsingle`` from the ``docs/docsite/rst/`` directory, you'll get ``make: *** No rule to make target `htmlsingle'. Stop.`` If you run it from ``docs/docsite/`` and provide the full path, you'll get ``sphinx-build: error: cannot find files ['rst/rst/community/documentation_contributions.rst']``.


		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:``

	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>`.
	Typos are everywhere, even in the Ansible documentation. We work hard to keep the documentation up-to-date, but you may also find outdated examples. We offer easy ways to :ref:`report and/or fix documentation errors <community_documentation_contributions>`.

Add docs about contributing to docs #46481

Add docs about contributing to docs #46481

Conversation

acozine commented Oct 4, 2018

SUMMARY

ISSUE TYPE

COMPONENT NAME

ANSIBLE VERSION

ansibot commented Oct 4, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

acozine commented Oct 18, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ansibot commented Oct 23, 2018

ansibot commented Oct 23, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment