Enable documentation in plugins #22796

bcoca · 2017-03-20T16:04:35Z

SUMMARY

Made ansible-doc more plugin agnostic
We can have docs in lookup, callback, connectionm strategy, etc
Use first docstring and make pepizis happy
generalized module_docs to plugin_docs
documented cartesian, ssh, default, jsonfile, etc as examples
fixes #12089

ISSUE TYPE

Feature Pull Request
Docs Pull Request

COMPONENT NAME

plugins

ANSIBLE VERSION

2.4

ADDITIONAL INFORMATION

TODO:

actually document all plugins in supported types, cannot use list until this is done (should list skip undoc?)
figure out how to integrate with website (probably similar to modules but in subsections)
figure out format for test/filters as they have multiple per file
figure out module_utils as these are really 'api for modules'
vars/inventory?
better definition of config (have 'file config/keyword/env var/inventory var' "aliases")
examples/return fields might need to be more format 'tolerant'
action plugins? these now are documented via the module files

gundalow

Looks good.
Consist used of capital letters and full stops on the descriptions would be nice to make everything consistent.

gundalow · 2017-03-20T17:02:04Z

lib/ansible/plugins/lookup/cartesian.py

+            description:
+                - a set of lists
+            required: True
+EXAMPLES:


Multi line yaml with key: value

Is the indentation correct?

how not so? just needs to be consistent, it can be 0,1... N spaces, i use 4

gundalow · 2017-03-20T17:02:26Z

lib/ansible/plugins/lookup/etcd.py

+DOCUMENTATION:
+    author:
+        - Jan-Piet Mens (@jpmens)
+    lookup: etc


will fix, concentrating more on 'method' than actual docs right now

gundalow · 2017-03-20T17:04:25Z

lib/ansible/utils/plugin_docs.py

+
+# modules that are ok that they do not have documentation strings
+BLACKLIST_MODULES = frozenset((
+    'async_wrapper',


Could we docs for this, or is this one of those fake modules?

its 'fake module' but we can add docs, we do intend to make it 'full module'

gundalow · 2017-03-20T17:05:54Z

lib/ansible/utils/plugin_docs.py

+        'doc': None,
+        'plainexamples': None,
+        'returndocs': None,
+        'metadata': {'metadata_version': '1.0', 'status': ['preview'], 'supported_by': 'community'},


Do we need default metadata? I wonder if in the future we can use CI to ensure this is present in all files, not just modules.

we plan to have 'community' plugins that are not core, so yes

bcoca · 2017-03-20T17:52:58Z

consider taht most docs in the plugins are 'example' they are not full/correct, but a starting point

abadger · 2017-03-21T19:16:44Z

lib/ansible/cli/doc.py

+
+            bkey = plugin_type.upper()
+            if bkey in plugin_docs.BLACKLIST and plugin in plugin_docs.BLACKLIST[bkey]:
+                self.args = self.args - plugin_docs.BLACKLIST[bkey]


This will error.

Probably what you want to do is move the call to sorted(self.args) from line 111 to line 116.

abadger · 2017-03-21T19:19:07Z

lib/ansible/cli/doc.py

+            self.args = sorted(set(self.plugin_list))
+
+            bkey = plugin_type.upper()
+            if bkey in plugin_docs.BLACKLIST and plugin in plugin_docs.BLACKLIST[bkey]:


Simpler to write: if plugin in plugin_docs.BLACKLIST.get(bkey, frozenset()):

(Just saw that this pattern happens in other places too.. ou can simplify everywhere that it occurs).

abadger · 2017-03-21T21:29:01Z

lib/ansible/cli/doc.py

+
+            bkey = plugin_type.upper()
+            if plugin in plugin_docs.BLACKLIST.get(bkey, ()):
+                self.args = sorted(self.args) - plugin_docs.BLACKLIST[bkey]


Actually... this is what I meant:

self.find_plugins(path) self.args = set(self.plugin_list) bkey = plugin_type.upper() if plugin in plugin_docs.BLACKLIST.get(bkey, frozenset()): self.args = self.args - plugin_docs.BLACKLIST[bkey] self.args = sorted(self.args)

abadger · 2017-03-22T00:26:01Z

lib/ansible/cli/doc.py

+                self.find_plugins(path)
+
+            bkey = plugin_type.upper()
+            if plugin in plugin_docs.BLACKLIST.get(bkey, ()):


I don't think plugin is defined at this point in the method.

ansibot · 2017-03-22T01:19:03Z

The test ansible-test sanity --test pep8 failed with the following errors:

lib/ansible/cli/doc.py:319:161: E501 line too long (173 > 160 characters)
lib/ansible/plugins/connection/ssh.py:33:23: W291 trailing whitespace
lib/ansible/plugins/connection/ssh.py:51:112: W291 trailing whitespace

click here for bot help

Made ansible-doc more plugin agnostic We can have docs in lookup, callback, connectionm strategy, etc Use first docstring and make pepizis happy generalized module_docs to plugin_docs documented cartesian, ssh, default, jsonfile, etc as examples changed lack of docs to warning when listing made smarter about bad docstrings better blacklisting added handling of options/config/envs/etc move blacklist to find_plugins, only need once

ansibot · 2017-03-22T02:16:04Z

The test ansible-test sanity --test pep8 failed with the following error:

lib/ansible/plugins/connection/ssh.py:32:23: W291 trailing whitespace

click here for bot help

ansibot · 2017-03-22T20:23:03Z

cc @dharmabumstead
click here for bot help

bcoca removed the needs_triage Needs a first human triage before being processed. label Mar 20, 2017

gundalow reviewed Mar 20, 2017

View reviewed changes

bcoca force-pushed the plugin_docs branch 2 times, most recently from 9a680b9 to 3c5a107 Compare March 20, 2017 20:29

ansibot added the c:plugins/connection/local label Mar 20, 2017

bcoca force-pushed the plugin_docs branch from 8b48f85 to 0f684b1 Compare March 20, 2017 21:56

This was referenced Mar 21, 2017

expand documentation fields ansible/proposals#58

Closed

Public Core Meeting Meeting - March 2017 ansible/community#156

Closed

abadger reviewed Mar 21, 2017

View reviewed changes

bcoca changed the title ~~[WIP] Enable documentation in plugins~~ Enable documentation in plugins Mar 21, 2017

bcoca removed the WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. label Mar 21, 2017

bcoca force-pushed the plugin_docs branch from 0d5d987 to 772798e Compare March 21, 2017 21:23

abadger reviewed Mar 21, 2017

View reviewed changes

abadger reviewed Mar 22, 2017

View reviewed changes

bcoca force-pushed the plugin_docs branch 2 times, most recently from 0c9f563 to c722f21 Compare March 22, 2017 00:48

ansibot added the needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. label Mar 22, 2017

bcoca force-pushed the plugin_docs branch from 8dc3b6d to 082d4b5 Compare March 22, 2017 01:47

uncommit the crime of extra spaces in docstring

5a9fa70

ansibot removed the needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. label Mar 22, 2017

updated doc man page

a55b456

ansibot added docs_pull_request needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. labels Mar 22, 2017

etcd doc tests

5727421

ansibot removed the needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. label Mar 23, 2017

bcoca merged commit 91a385b into ansible:devel Mar 23, 2017

bcoca deleted the plugin_docs branch March 23, 2017 05:27

ansibot added docs This issue/PR relates to or includes documentation. feature This issue/PR relates to a feature request. and removed docs_pull_request labels Mar 4, 2018

ansible locked and limited conversation to collaborators Apr 26, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Enable documentation in plugins #22796

Enable documentation in plugins #22796

bcoca commented Mar 20, 2017 •

edited

Loading

gundalow left a comment

gundalow Mar 20, 2017

bcoca Mar 20, 2017

gundalow Mar 20, 2017

bcoca Mar 20, 2017

gundalow Mar 20, 2017

bcoca Mar 20, 2017

gundalow Mar 20, 2017

bcoca Mar 20, 2017

bcoca commented Mar 20, 2017

abadger Mar 21, 2017

abadger Mar 21, 2017

bcoca Mar 21, 2017

abadger Mar 21, 2017 •

edited

Loading

bcoca Mar 21, 2017

abadger Mar 21, 2017

abadger Mar 21, 2017

abadger Mar 22, 2017

ansibot commented Mar 22, 2017

ansibot commented Mar 22, 2017

ansibot commented Mar 22, 2017

Enable documentation in plugins #22796

Enable documentation in plugins #22796

Conversation

bcoca commented Mar 20, 2017 • edited Loading

SUMMARY

ISSUE TYPE

COMPONENT NAME

ANSIBLE VERSION

ADDITIONAL INFORMATION

gundalow left a 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

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

bcoca commented Mar 20, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abadger Mar 21, 2017 • edited Loading

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 Mar 22, 2017

ansibot commented Mar 22, 2017

ansibot commented Mar 22, 2017

bcoca commented Mar 20, 2017 •

edited

Loading

abadger Mar 21, 2017 •

edited

Loading