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

Enable documentation in plugins #22796

Merged
merged 4 commits into from Mar 23, 2017

Conversation

@bcoca
Copy link
Member

commented Mar 20, 2017

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
Copy link
Contributor

left a comment

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

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

This comment has been minimized.

Copy link
@gundalow

gundalow Mar 20, 2017

Contributor

Multi line yaml with key: value

Is the indentation correct?

This comment has been minimized.

Copy link
@bcoca

bcoca Mar 20, 2017

Author Member

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

lib/ansible/plugins/lookup/etcd.py Outdated
DOCUMENTATION:
author:
- Jan-Piet Mens (@jpmens)
lookup: etc

This comment has been minimized.

Copy link
@gundalow

gundalow Mar 20, 2017

Contributor

etcd

This comment has been minimized.

Copy link
@bcoca

bcoca Mar 20, 2017

Author Member

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

lib/ansible/utils/plugin_docs.py Outdated

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

This comment has been minimized.

Copy link
@gundalow

gundalow Mar 20, 2017

Contributor

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

This comment has been minimized.

Copy link
@bcoca

bcoca Mar 20, 2017

Author Member

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

lib/ansible/utils/plugin_docs.py Outdated
'doc': None,
'plainexamples': None,
'returndocs': None,
'metadata': {'metadata_version': '1.0', 'status': ['preview'], 'supported_by': 'community'},

This comment has been minimized.

Copy link
@gundalow

gundalow Mar 20, 2017

Contributor

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.

This comment has been minimized.

Copy link
@bcoca

bcoca Mar 20, 2017

Author Member

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

@bcoca

This comment has been minimized.

Copy link
Member Author

commented Mar 20, 2017

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

@bcoca bcoca force-pushed the bcoca:plugin_docs branch 2 times, most recently Mar 20, 2017

@bcoca bcoca force-pushed the bcoca:plugin_docs branch Mar 20, 2017

lib/ansible/cli/doc.py Outdated

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 comment has been minimized.

Copy link
@abadger

abadger Mar 21, 2017

Member

This will error.

This comment has been minimized.

Copy link
@abadger

abadger Mar 21, 2017

Member

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

This comment has been minimized.

Copy link
@bcoca

bcoca Mar 21, 2017

Author Member

?

lib/ansible/cli/doc.py Outdated
self.args = sorted(set(self.plugin_list))

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

This comment has been minimized.

Copy link
@abadger

abadger Mar 21, 2017

Member

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

This comment has been minimized.

Copy link
@bcoca

bcoca Mar 21, 2017

Author Member

will do

This comment has been minimized.

Copy link
@abadger

abadger Mar 21, 2017

Member

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

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

@bcoca bcoca removed the WIP label Mar 21, 2017

@bcoca bcoca force-pushed the bcoca:plugin_docs branch Mar 21, 2017

lib/ansible/cli/doc.py Outdated

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

This comment has been minimized.

Copy link
@abadger

abadger Mar 21, 2017

Member

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)
lib/ansible/cli/doc.py Outdated
self.find_plugins(path)

bkey = plugin_type.upper()
if plugin in plugin_docs.BLACKLIST.get(bkey, ()):

This comment has been minimized.

Copy link
@abadger

abadger Mar 22, 2017

Member

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

@bcoca bcoca force-pushed the bcoca:plugin_docs branch 2 times, most recently Mar 22, 2017

@ansibot

This comment has been minimized.

Copy link
Contributor

commented Mar 22, 2017

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

Enable documentation in plugins
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

@bcoca bcoca force-pushed the bcoca:plugin_docs branch to 082d4b5 Mar 22, 2017

@ansibot

This comment has been minimized.

Copy link
Contributor

commented Mar 22, 2017

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 ansibot removed the needs_revision label Mar 22, 2017

@ansibot

This comment has been minimized.

Copy link
Contributor

commented Mar 22, 2017

@ansibot ansibot removed the needs_revision label Mar 23, 2017

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

1 check passed

Shippable Run 17009 status is SUCCESS.
Details

@bcoca bcoca deleted the bcoca:plugin_docs branch Mar 23, 2017

@bcoca bcoca added this to Done in ansible config Sep 27, 2017

@ansibot ansibot added docs feature and removed docs_pull_request labels Mar 4, 2018

@ansible ansible locked and limited conversation to collaborators Apr 26, 2019

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