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
Choose a base branch
from

Conversation

dagwieers
Copy link
Member

@dagwieers dagwieers commented Sep 18, 2018

SUMMARY

This PR includes:

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 This issue/PR relates to or includes documentation. label Sep 18, 2018
@acozine
Copy link
Contributor

acozine commented Sep 18, 2018

@dagwieers is this a replacement for #42888?

@ansibot ansibot added affects_2.8 This issue/PR affects Ansible v2.8 support:core This issue/PR relates to code supported by the Ansible Engineering Team. labels Sep 18, 2018
@dagwieers
Copy link
Member Author

@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 OLD 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
@ansibot

This comment has been minimized.

@ansibot ansibot added needs_rebase https://docs.ansible.com/ansible/devel/dev_guide/developing_rebasing.html needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. labels 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 changed the title [WIP] Docs: Show parameter types (in purple) [WIP] Docs: Read arg_spec documentation from module Sep 19, 2018
@ansibot
Copy link
Contributor

ansibot commented Sep 19, 2018

@ansibot ansibot added WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. aci Cisco ACI community module This issue/PR relates to a module. networking Network category and removed needs_rebase https://docs.ansible.com/ansible/devel/dev_guide/developing_rebasing.html labels Sep 19, 2018
@gundalow
Copy link
Contributor

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

Choose a reason for hiding this comment

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

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 September 19, 2018 06:35
@dagwieers
Copy link
Member Author

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
@ansibot ansibot added stale_ci This PR has been tested by CI more than one week ago. Close and re-open this PR to get it retested. and removed WIP This issue/PR is a work in progress. Nevertheless it was shared for getting input from peers. labels Jan 9, 2019
@ansibot ansibot removed needs_rebase https://docs.ansible.com/ansible/devel/dev_guide/developing_rebasing.html stale_ci This PR has been tested by CI more than one week ago. Close and re-open this PR to get it retested. labels Jan 14, 2019
@mattclay mattclay added the ci_verified Changes made in this PR are causing tests to fail. label Jan 15, 2019
@ansibot ansibot added needs_rebase https://docs.ansible.com/ansible/devel/dev_guide/developing_rebasing.html stale_ci This PR has been tested by CI more than one week ago. Close and re-open this PR to get it retested. labels Jan 23, 2019
@ansibot ansibot added the files Files category label Mar 4, 2019
@ansibot ansibot added the needs_triage Needs a first human triage before being processed. label May 16, 2020
@acozine acozine removed the needs_triage Needs a first human triage before being processed. label Jul 2, 2020
@ansibot ansibot added pre_azp This PR was last tested before migration to Azure Pipelines. and removed ci_verified Changes made in this PR are causing tests to fail. stale_ci This PR has been tested by CI more than one week ago. Close and re-open this PR to get it retested. labels Dec 9, 2020
Copy link
Contributor

@acozine acozine left a comment

Choose a reason for hiding this comment

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

Can we close this? It's pre-collections and the project has moved on. If this is something we want to try in future, let's start fresh.

@ansibot ansibot added stale_review Updates were made after the last review and the last review is more than 7 days old. and removed networking Network category has_issue labels Jul 12, 2023
@ansibot ansibot added needs_rebase https://docs.ansible.com/ansible/devel/dev_guide/developing_rebasing.html and removed needs_rebase https://docs.ansible.com/ansible/devel/dev_guide/developing_rebasing.html labels Oct 24, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
affects_2.8 This issue/PR affects Ansible v2.8 docs This issue/PR relates to or includes documentation. files Files category module This issue/PR relates to a module. needs_rebase https://docs.ansible.com/ansible/devel/dev_guide/developing_rebasing.html needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. pre_azp This PR was last tested before migration to Azure Pipelines. stale_review Updates were made after the last review and the last review is more than 7 days old. support:core This issue/PR relates to code supported by the Ansible Engineering Team. test This PR relates to tests.
Projects
No open projects
Development

Successfully merging this pull request may close these issues.

None yet

9 participants