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

Jump to bottom

Update plugin docs #75050

Merged
merged 9 commits into from Jun 21, 2021
Merged

Update plugin docs #75050

merged 9 commits into from Jun 21, 2021

Conversation

acozine
Copy link
Contributor

@acozine acozine commented Jun 17, 2021

SUMMARY

Closes #73327
Supersedes #74769

Adds a page for every plugin type, adds cross-linking to multiple related topics, edits existing plugin pages for style, etc.

ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME

docs.ansible.com

@ansibot
Copy link
Contributor

ansibot commented Jun 17, 2021

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

docs/docsite/rst/index.rst:0:0: unknown: 
docs/docsite/rst/index.rst:0:0: unknown: -------------------
docs/docsite/rst/index.rst:0:0: unknown: ----------------------
docs/docsite/rst/index.rst:0:0: unknown: =============
docs/docsite/rst/index.rst:0:0: unknown: Enabling docs fragments
docs/docsite/rst/index.rst:0:0: unknown: Enabling filter plugins
docs/docsite/rst/index.rst:0:0: unknown: Filter plugins
docs/docsite/rst/index.rst:0:0: unknown: Using filter plugins
docs/docsite/rst/plugins/docs_fragment.rst:15:0: warning: Title underline too short.
docs/docsite/rst/plugins/filter.rst:4:0: warning: Title underline too short.
docs/docsite/rst/plugins/filter.rst:15:0: warning: Title underline too short.
docs/docsite/rst/plugins/filter.rst:22:0: warning: Title underline too short.
docs/docsite/rst/plugins/inventory.rst:10:0: undefined-label: undefined label: _developing_inventory_plugins (if the link has no caption the label must precede a section header)
docs/docsite/rst/plugins/lookup.rst:10:0: undefined-label: undefined label: _developing_lookup_plugins (if the link has no caption the label must precede a section header)

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

docs/docsite/rst/plugins/docs_fragment.rst:15:0: Title underline too short.
docs/docsite/rst/plugins/filter.rst:4:0: Title underline too short.

click here for bot help

@ansibot ansibot added WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. affects_2.12 docs This issue/PR relates to or includes documentation. docs_only All changes are to files within the docs/docsite/ directory needs_triage Needs a first human triage before being processed. new_plugin This PR includes a new plugin. support:core This issue/PR relates to code supported by the Ansible Engineering Team. labels Jun 17, 2021
@acozine acozine mentioned this pull request Jun 17, 2021
Closed
@acozine acozine requested a review from Qalthos June 18, 2021 15:28
@acozine acozine changed the title WIP: Update plugin docs Update plugin docs Jun 18, 2021
@ansibot ansibot added core_review In order to be merged, this PR must follow the core review workflow. and removed WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. labels Jun 18, 2021
tadeboro
tadeboro suggested changes Jun 20, 2021
View reviewed changes
Copy link
Contributor

@tadeboro tadeboro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found a few Freenode references in the docs, but apart from that, things do look OK from my side.

docs/docsite/rst/plugins/docs_fragment.rst Outdated
An guide to creating Ansible collections
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should point to Libera.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well spotted! I've fixed those in 6f2b1c7

docs/docsite/rst/plugins/filter.rst Outdated
Lookup plugins
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should point to Libera.

docs/docsite/rst/plugins/module_util.rst Outdated
An guide to creating Ansible collections
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Libera.

docs/docsite/rst/plugins/module_util.rst Outdated
:local:
:depth: 2

Module utilities contain shared code used by multiple modules. You can write :ref:`custom module utilities <developing_module_utilities>`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code from the module_utils directory can (and often is) also used by other plugin kinds, not only modules.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, good catch, thanks

docs/docsite/rst/plugins/terminal.rst Outdated
Network netconf plugins
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Libera.

docs/docsite/rst/plugins/test.rst Outdated
Lookup plugins
`User Mailing List <https://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!
`irc.freenode.net <http://irc.freenode.net>`_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Libera.

docs/docsite/rst/plugins/action.rst
==============

.. contents::
:local:
:depth: 2

Action plugins act in conjunction with :ref:`modules <working_with_modules>` to execute the actions required by playbook tasks.
They usually execute automatically in the background doing prerequisite work before modules execute.
Action plugins act in conjunction with :ref:`modules <working_with_modules>` to execute the actions required by playbook tasks. They usually execute automatically in the background doing prerequisite work before modules execute.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should add something along the lines of "action plugin is the control node part of a module"? This should help explain why action plugins share their documentation with the module.

@ansibot ansibot added 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 Jun 20, 2021
@ansibot 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 Jun 21, 2021
@ansibot ansibot added 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 Jun 21, 2021
@ansibot ansibot added core_review In order to be merged, this PR must follow the core review workflow. needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. and removed needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. core_review In order to be merged, this PR must follow the core review workflow. labels Jun 21, 2021
samccann
samccann reviewed Jun 21, 2021
View reviewed changes
Copy link
Contributor

@samccann samccann left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one nit

docs/docsite/rst/plugins/callback.rst Outdated Show resolved Hide resolved
@acozine @samccann
Update docs/docsite/rst/plugins/callback.rst
696c2d6 
Co-authored-by: Sandra McCann <samccann@redhat.com>
tadeboro
tadeboro approved these changes Jun 21, 2021
View reviewed changes
Copy link
Contributor

@tadeboro tadeboro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, @acozine, for preparing this PR.

@ansibot ansibot added needs_ci This PR requires CI testing to be performed. Please close and re-open this PR to trigger CI. core_review In order to be merged, this PR must follow the core review workflow. and removed needs_ci This PR requires CI testing to be performed. Please close and re-open this PR to trigger CI. needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. labels Jun 21, 2021
@samccann samccann removed the needs_triage Needs a first human triage before being processed. label Jun 21, 2021
@samccann samccann merged commit a7be495 into ansible:devel Jun 21, 2021
@Akasurde Akasurde mentioned this pull request Jun 22, 2021
Closed
@acozine acozine deleted the update_plugin_docs branch June 22, 2021 14:54
@acozine acozine mentioned this pull request Jun 25, 2021
Closed
@ansible ansible locked and limited conversation to collaborators Jul 19, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@Akasurde Akasurde Akasurde left review comments

@samccann samccann samccann left review comments

@tadeboro tadeboro tadeboro approved these changes

@Qalthos Qalthos Awaiting requested review from Qalthos

Assignees
No one assigned
Labels
affects_2.12 core_review In order to be merged, this PR must follow the core review workflow. docs_only All changes are to files within the docs/docsite/ directory docs This issue/PR relates to or includes documentation. new_plugin This PR includes a new plugin. support:core This issue/PR relates to code supported by the Ansible Engineering Team.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Problems with the list of plugins in plugins/plugins.rst
5 participants
@acozine @ansibot @tadeboro @Akasurde @samccann