saltstack / saltstack/salt

[DOCS] Audit and ensure all args listed in $(salt --help) will match with $(man 1 salt)

Open
#60,677 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

documentation severity-medium time-estimate-long-term
Dominant language
Python
Stars
15.7k
Forks
5.6k
Avg merge
2d 44m
Merged PRs (30d)
80

Description

Description

This is created as a follow-up to #60629

Args are missing and/or have differing help description documentation between:

  • salt/utils/parsers.py
  • doc/ref/cli/salt.rst

An audit needs to be done to see what is missing and needs to be added to doc/ref/cli/salt.rst.

Suggested Fix

Audit and update the docs.

After updating, new issue(s) should be created for next steps depending on outcome:

  • If audit concludes they are meant to mirror each other, then automation should be created to help sync what they contain.
  • If they are meant to differ, then a different plan can come into play.

Type of documentation

  • Salt documentation
  • Salt modules
  • Man pages (which get autogenerated from the docs, such as salt.1 and salt.7)

Location or format of documentation

  • salt --help (is salt/utils/parsers.py output)
  • man 1 salt or man 7 salt (is rendered doc/man/* docs, which are generated by Sphinx, converting source docs such as doc/ref/cli/salt.rst for salt.1)
  • Rendered HTML of doc/ref/cli/salt.rst

Additional context
Add any other context or screenshots about the feature request here.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare the argument definitions in salt/utils/parsers.py with the documentation in doc/ref/cli/salt.rst; start by reviewing salt --help and man 1 salt to identify missing or differing entries. Update the documentation so the audit's discrepancies are addressed, then verify the rendered man-page and HTML sources reflect the intended result.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.