[DOCS] Identify Module functions that only work on specific OS/Distros in the docs
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 15.7k
- Forks
- 5.6k
- Avg merge
- 2d 44m
- Merged PRs (30d)
- 80
Description
Description
It is confusing in the Modules documentation when a specific module function looks like it is a perfect match for your use case only to find that it only works on specific operating systems. A perfect example of this is https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.system.html#salt.modules.system.get_reboot_required_witnessed. There is no indication on this page that it would not work across all operating system types. But if you look at the code this has a decorator that limits it to only working on NILRT systems. also described here https://github.com/saltstack/salt/issues/58125#issuecomment-846296346
Suggested Fix
Would it be possible to specify in the documentation when a function is not available on given operating system. I recognize this is not practical to do manually as it could quickly get out of date. I was wondering if there was a way to pull any @depends decorators from the code dynamically and use this in the docs page.
Type of documentation
Salt Modules
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
Start with the Salt Modules documentation page for salt.modules.system.get_reboot_required_witnessed and the linked discussion in issue #58125. Trace how its @depends decorator is represented in the documentation and assess whether the docs can derive availability automatically. Done means module function documentation identifies operating-system or distribution restrictions without requiring readers to inspect the code.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100