saltstack / saltstack/salt

[DOCS]Documentation py renderer needs upgrade

Open
#63,698 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Description
I am writing Salt code using the Python renderer. The documentation about how to write usable code with this renderer, is very vague and is missing a lot of pointers. And that is very disappointing.

Suggested Fix
What did you expect to see in the documentation that is missing or needs updating?

Some missed points:

  • How to check results of states, the pythonic way. Ex: How to check if result is False?
  • Possibilities for storing values from states. With examples.
  • A example of how to use an Salt module (I picked my brain many hours on this)
    Should it be like this or are there better ways?
    config['check_pass_secured_url'] = { 'module.run': [ { 'http.query': { 'url': url, 'username': 'testing'), 'password': 'testing') }, } ], }

Type of documentation
Salt documentation

Location or format of documentation
Insert page URL if applicable.

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

Start with the Salt Python renderer page at https://docs.saltproject.io/en/latest/ref/renderers/all/salt.renderers.py.html and compare its guidance with the requested use cases. Document how to inspect state results, store values, and call Salt modules, with clear examples; the work is done when these workflows are explained and the page is no longer vague.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.