Skip to content
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

dev_guide: Various small updates #53273

Open
wants to merge 11 commits into
base: devel
from

Conversation

Projects
None yet
4 participants
@dagwieers
Copy link
Member

dagwieers commented Mar 4, 2019

SUMMARY

These are clarifications that I usually remark when doing reviews

This PR includes:

  • Consistent use of parameter rather than option
  • Clarify capitalization and yes/no values
  • Added # -*- coding: utf-8 -*- statement
  • Clarify multiple description-entries
  • Don't use quotes if YAML does not require it
  • Use raw strings for EXAMPLES and RETURN examples
  • Fix incorrect string type in RETURN examples
ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME

dev_guide

Various small updates
These are clarifications that I usually remark when doing reviews

@dagwieers dagwieers requested review from acozine and gundalow Mar 4, 2019

@dagwieers dagwieers changed the title Various small updates dev_guide: Various small updates Mar 4, 2019

@ansibot

This comment has been minimized.

Copy link
Contributor

ansibot commented Mar 4, 2019


:deprecated:

* Marks modules that will be removed in future releases. See also :ref:`module_lifecycle`.

:options:

* If the module has no options (for example, it's a ``_facts`` module), all you need is one line: ``options: {}``.
* If your module has options (in other words, accepts arguments), each option should be documented thoroughly. For each module argument/option, include:
* Options are usually called `parameters` and sometimes arguments. We will be using `parameters` for the remainder of the documentation.

This comment has been minimized.

@acozine

acozine Mar 4, 2019

Contributor

The documentation field is called options, not parameters - so it's a bit confusing to say "create a field called options" and then document it as if it were called parameters. I like the move toward consistency, for sure, but describing a field with one name using a different name seems like a step backward.

This comment has been minimized.

@dagwieers

dagwieers Mar 11, 2019

Author Member

Sure, but we use 'parameter' almost everywhere else (including the module documentation), so why complicate things in the documentation, just because it is called options in the module docs spec? I am all for renaming this part in Ansible too, but that won't happen in this PR.

This comment has been minimized.

@dagwieers

dagwieers Mar 11, 2019

Author Member

PS We are already having 3 names (option, argument, parameter) for the same thing, so I don't think my changes is taking a step backward. At least we are clarifying that it is the same thing, and we standardize on a single name. That is a step forward.

@ansibot ansibot removed the needs_triage label Mar 4, 2019

@acozine
Copy link
Contributor

acozine left a comment

I'm still -1 on the use of parameter when the field is still called option. Lots of other good changes in this PR though.

I made a few copyedits in this review. I find the use of "the coding" confusing - if I'm reading a later paragraph I might think that's referring to python code/coding, so I've suggested using "UTF-8 coding" for clarity.

Show resolved Hide resolved docs/docsite/rst/dev_guide/developing_modules_documenting.rst Outdated
Show resolved Hide resolved docs/docsite/rst/dev_guide/developing_modules_documenting.rst Outdated
Show resolved Hide resolved docs/docsite/rst/dev_guide/developing_modules_documenting.rst Outdated
Show resolved Hide resolved docs/docsite/rst/dev_guide/developing_modules_documenting.rst Outdated
Show resolved Hide resolved docs/docsite/rst/dev_guide/developing_modules_documenting.rst Outdated
If your module returns facts that are often needed, an example of how to use them can be helpful.

.. _return_block:

RETURN block
============

After the shebang, the copyright line, the license, the ``ANSIBLE_METADATA`` section, ``DOCUMENTATION`` and ``EXAMPLES`` blocks comes the ``RETURN`` block. This section documents the information the module returns for use by other modules.
After the shebang, the coding, the copyright line, the license, the ``ANSIBLE_METADATA`` section, ``DOCUMENTATION`` and ``EXAMPLES`` blocks comes the ``RETURN`` block. This section documents the information the module returns for use by other modules.

This comment has been minimized.

@acozine

acozine Mar 11, 2019

Contributor
Suggested change
After the shebang, the coding, the copyright line, the license, the ``ANSIBLE_METADATA`` section, ``DOCUMENTATION`` and ``EXAMPLES`` blocks comes the ``RETURN`` block. This section documents the information the module returns for use by other modules.
After the shebang, the UTF-8 coding, the copyright line, the license, the ``ANSIBLE_METADATA`` section, ``DOCUMENTATION`` and ``EXAMPLES`` blocks comes the ``RETURN`` block. This section documents the information the module returns for use by other modules.
Show resolved Hide resolved docs/docsite/rst/dev_guide/developing_modules_documenting.rst Outdated
Show resolved Hide resolved docs/docsite/rst/dev_guide/developing_modules_documenting.rst Outdated
Show resolved Hide resolved docs/docsite/rst/dev_guide/developing_modules_documenting.rst Outdated
Show resolved Hide resolved docs/docsite/rst/dev_guide/developing_modules_documenting.rst Outdated

acozine and others added some commits Mar 11, 2019

Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>
Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>
Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>
Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>
Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>
Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>
Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>
Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>
@dagwieers

This comment has been minimized.

Copy link
Member Author

dagwieers commented Mar 11, 2019

I don't like the term coding either, using encoding would be much better. But the line says coding: so we are referring that, using anything else would be more confusing...

acozine and others added some commits Mar 11, 2019

Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>
Update docs/docsite/rst/dev_guide/developing_modules_documenting.rst
Co-Authored-By: dagwieers <dag@wieers.com>

@ansibot ansibot added core_review and removed needs_revision labels Mar 12, 2019


.. _note:
* in 2.8 the Ansible directories for doc fragments changed, see documentation of previous versions to find the old locations.
* in Ansible 2.8 the Ansible directories for doc fragments changed, see documentation of previous versions to find the old locations.

This comment has been minimized.

@gundalow

gundalow Mar 18, 2019

Contributor

Can we just state that:

prior to Ansible 2.8 this was in lib/ansible/utils/module_docs_fragments

Rather than making people have to look it up?

@gundalow

This comment has been minimized.

Copy link
Contributor

gundalow commented Mar 18, 2019

Thanks for doing this, good tidy up.
I do think module options makes more sense

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.