[DOCS] Audit and ensure all args listed in $(salt --help) will match with $(man 1 salt)
Nobody has claimed this yet.
- 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.pydoc/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.1andsalt.7)
Location or format of documentation
salt --help(issalt/utils/parsers.pyoutput)man 1 saltorman 7 salt(is rendereddoc/man/*docs, which are generated by Sphinx, converting source docs such asdoc/ref/cli/salt.rstforsalt.1)- Rendered HTML of
doc/ref/cli/salt.rst
Additional context
Add any other context or screenshots about the feature request here.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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