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

SSH connection plugin docs are broken #74838

Closed
1 task done
acozine opened this issue May 26, 2021 · 6 comments · Fixed by ansible-community/antsibull#307 or #75787
Closed
1 task done

SSH connection plugin docs are broken #74838

acozine opened this issue May 26, 2021 · 6 comments · Fixed by ansible-community/antsibull#307 or #75787
Labels
affects_2.11 docs This issue/PR relates to or includes documentation. has_pr This issue has an associated PR. support:core This issue/PR relates to code supported by the Ansible Engineering Team.

Comments

@acozine
Copy link
Contributor

acozine commented May 26, 2021

Summary

Current output looks like this:

Screen Shot 2021-05-26 at 3 47 04 PM

The problem is currently in devel and in latest docs (links to latest and devel). Cause of the issue appears to be here:

https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/connection/ssh.py#L80

Introduced by #73708.

Issue Type

Documentation Report

Component Name

ssh connection plugin

Ansible Version

$ ansible --version
devel and 2.11

Configuration

$ ansible-config dump --only-changed
N/A

OS / Environment

N/A

Additional Information

No other relevant information.

Code of Conduct

  • I agree to follow the Ansible Code of Conduct
@ansibot
Copy link
Contributor

ansibot commented May 26, 2021

Files identified in the description:

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

@ansibot ansibot added affects_2.11 docs This issue/PR relates to or includes documentation. needs_triage Needs a first human triage before being processed. support:core This issue/PR relates to code supported by the Ansible Engineering Team. labels May 26, 2021
@abadger
Copy link
Contributor

abadger commented May 27, 2021

ansible-community/antsibull#277 should fix the breakage to the docs build. However, I noted in this comment: ansible-community/antsibull#277 (comment) that the new field doesn't follow the conventions of similar fields (ini:, env:, vars:) and doesn't carry enough user-visible information in it to be at all useful for creating docs for the ssh plugin. Since it's only in devel, perhaps this feature should be removed and rethought. It could be enhanced to have more information to make it a proper piece of documentation or it might be better to not do it inside of DOCUMENTATION/the config subsystem because it doesn't work with a pluggable source of information like the other pieces of config so it will always be tied to things that ansible-core chooses to implement rather than truly extensible by any third party's plugin.

@ansibot ansibot added the has_pr This issue has an associated PR. label May 27, 2021
@samdoran samdoran removed the needs_triage Needs a first human triage before being processed. label May 27, 2021
@bcoca
Copy link
Member

bcoca commented May 27, 2021

It is not only in devel, it should be present in 2.11, also cli was always part of the design for config, but so are others that are still not used/usable everywhere see #66139 (comment)

The user visible information was always supposed to be there, but we missed adding the PR that did so (here it is now #74847).

As with keywords, cli it was never meant to be 'producible' by author but to reflect existing usage in core.

I always meant on writing a full spec. which is mostly what is holding up #71734, had several conversations with felix on that. But the feature is also not complete yet and will still take some time to finish defining.

Previously docs build was not validating these fields, if I had known I would have warned and worked with docs team about adding this one once it was used. Also this field will make it's way into the configuration (base.yml) as a way to document which settings can be overridden from the CLI, so it should not be restricted there either.

@felixfontein
Copy link
Contributor

The devel docs are broken again since now there's a new option field (added in 26827f5). I've implemented a fix for that in ansible-community/antsibull#306.

@felixfontein
Copy link
Contributor

(That commit belongs to the above-mentioned #74847.)

@felixfontein
Copy link
Contributor

resolved_by_pr ansible-community/antsibull#307

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
affects_2.11 docs This issue/PR relates to or includes documentation. has_pr This issue has an associated PR. support:core This issue/PR relates to code supported by the Ansible Engineering Team.
Projects
None yet
6 participants