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

Docs: Read arg_spec documentation from module #45805

Open
wants to merge 6 commits into
base: devel
from

Conversation

@dagwieers
Copy link
Member

@dagwieers dagwieers commented Sep 18, 2018

SUMMARY

This PR includes:

  • Reading arg_spec documentation from module
    (no longer do we need to duplicate parameter details in documentation)
  • Showing parameter type for every parametermoved to #49966
  • Show type in purplemoved to #49966
  • Convert types to fully written variantmoved to #49966

To do:

  • Fix support for suboptions
  • Add support for ansible-doc
  • And we can also auto-generate things like:
    • "This parameter is deprecated and will be removed in Ansible X.Y" (removed_in_version)
    • "This module supports check-mode" (supports_checkmode)
    • "Parameter x is mutual exclusive with parameter y" (mutually_exclusive)
    • "Parameter x and y need to be used together" (required_together)

Impact:

  • Contributors no longer have to ensure documentation matches the module arg_spec.
  • Reviewers don't need to verify the documentation, only descriptions.
  • Should work transparently, so we can clean up the modules in a phased manner.
ISSUE TYPE
  • Docs Pull Request
COMPONENT NAME

Module docs

ANSIBLE VERSION

v2.8 and earlier

ADDITIONAL INFORMATION

screenshot from 2018-09-18 18-26-00

@dagwieers dagwieers added the docs label Sep 18, 2018
@dagwieers dagwieers requested a review from acozine Sep 18, 2018
@acozine
Copy link
Contributor

@acozine acozine commented Sep 18, 2018

@dagwieers is this a replacement for #42888?

@dagwieers
Copy link
Member Author

@dagwieers dagwieers commented Sep 18, 2018

@acozine Not really, this is about adding types the right way. I hope we can find a better solution for indicating required parameters.

@acozine acozine added this to To do in Ansible Documentation via automation Sep 18, 2018
@dagwieers dagwieers changed the title Show parameter types (in purple) Docs: Show parameter types (in purple) Sep 18, 2018
@dagwieers dagwieers force-pushed the dagwieers:module-docs-type branch Sep 19, 2018
@ansibot

This comment has been hidden.

@dagwieers dagwieers force-pushed the dagwieers:module-docs-type branch Sep 19, 2018
@dagwieers dagwieers changed the title Docs: Show parameter types (in purple) [WIP] Docs: Show parameter types (in purple) Sep 19, 2018
@dagwieers dagwieers requested a review from gundalow Sep 19, 2018
@dagwieers dagwieers changed the title [WIP] Docs: Show parameter types (in purple) [WIP] Docs: Read arg_spec documentation from module Sep 19, 2018
@gundalow
Copy link
Contributor

@gundalow gundalow commented Sep 19, 2018

Could you please split out the module changes from the docs changes to allow us to backport as needed.

Copy link
Contributor

@gundalow gundalow left a comment

Great idea

I know this is WIP, but I hough some initial thoughts.

If we go ahead with this I think it would need to be multiple PRs
PR1: plugin formatter & template - could be back ported into stable-2.7
PR2: remove type from validate-modules's schema.py`, remove from How to document your module, remove from all modules. No nsure if we've want to backport that, would need to ask Toshio.

We can revisit this after AnsibleFest.

docs/bin/plugin_formatter.py Outdated Show resolved Hide resolved
docs/bin/plugin_formatter.py Outdated Show resolved Hide resolved
docs/templates/plugin.rst.j2 Outdated Show resolved Hide resolved
docs/templates/plugin.rst.j2 Outdated Show resolved Hide resolved
@gundalow gundalow requested a review from sivel Sep 19, 2018
@dagwieers
Copy link
Member Author

@dagwieers dagwieers commented Sep 19, 2018

This is a WIP, and for testing I need to have these modules in the same branch.

I do not plan to rewrite every module doc, the whole purpose of this implementation is that this is not required. We merge the docs with the arg_spec, but the docs have priority over the arg_spec.

The only thing we need in the arg_spec is a way to hide certain stuff from the docs. As some modules have parameters that should not be exposed to the user.

@dagwieers dagwieers added this to In progress in Contributor Experience via automation Sep 19, 2018
@ansible ansible deleted a comment from webknjaz Sep 19, 2018
@ansible ansible deleted a comment from webknjaz Sep 19, 2018
@dagwieers dagwieers force-pushed the dagwieers:module-docs-type branch Sep 19, 2018
@dagwieers dagwieers force-pushed the dagwieers:module-docs-type branch 3 times, most recently Dec 19, 2018
@mattclay mattclay removed the bot_broken label Jan 9, 2019
@ansibot

This comment has been hidden.

@ansibot ansibot added stale_ci and removed WIP labels Jan 9, 2019
dagwieers added 6 commits Sep 18, 2018
This PR includes:
- Showing parameter type for every parameter
- Show type in purple
- Convert types to fully written variant
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Contributor Experience
  
In progress
Linked issues

Successfully merging this pull request may close these issues.

None yet

9 participants