Documentation consistency improvements #59093
Conversation
eliasp
force-pushed
the
doc-consistency
branch
2 times, most recently
from
8137daf
to
245e86e
Compare
eliasp
force-pushed
the
doc-consistency
branch
from
8a784a4
to
5d23eb4
Compare
|
Don't have time right now to add further improvements, so I'm switching from WIP to "Ready for Review" and also just rebased it on latest master. |
- use "verbatim" for variables etc. - consistent upper-casing for acronyms (e.g. CLI) - use rST for return data and return types - use :mod: to link to related modules/functions - correct code type for Jinja snippet
Until now, the listings of all kinds of modules looked quite
inconsistent like this:
- salt.states.smtp
- salt.states.snapper module
- salt.states.solrcloud module
- salt.states.splunk
The `module` suffix is redundant anyways, so let's remove it and do some
further cleanup (adjusting overline/underline usage, underline length)
using the following bash script:
```bash
sed -i 's|\s\+module$||g' doc/ref/*/all/*.*.rst
for rst in doc/ref/*/all/*.*.rst;
do
# enforce consistent overline/underline usage, remove all overlines
if [[ $(head -n1 "${rst}") =~ ^=+$ ]];
then
sed -i -e 1d "${rst}"
fi
# adjust the length of the underline to the length of the module name
module_name=$(head -n1 "${rst}")
underline=$(for i in $(seq ${#module_name}); do echo -n "="; done)
sed -i '2s|^=\+$|'"${underline}"'|g' "${rst}"
done
```
The bug was fixed 7 years ago, the distribution release in question was EOL'd 1,5 years ago.
- use "verbatim" for variables etc. - use :mod: to link to related modules/functions - fix indentation, causing a parameter doc to be displayed as quote - use PGP instead of GPG where appropriate (PGP is the standard, GPG/GnuPG the implementation) - minor grammar/wording improvements
eliasp
force-pushed
the
doc-consistency
branch
from
5d23eb4
to
4d39a83
Compare
|
Rebased it on latest saltstack:master to fix the merge conflicts. |
There was a problem hiding this comment.
My only feedback is with the changes to salt/states/pkgrepo.py when it comes to GPG being changed to PGP. Is there a good justification for why this needs to be modified in this states module? Isn't GPG an open source standard implementation of PGP, and that most of these should still be saying GPG? It's difficult for me to discern whether any reference to a "GPG key" is an accidental online phenomenon of people incorrectly using it interchangeably with "PGP key" or whether the true definition is always a PGP key that is being mistaken. It seems that since it is a non-proprietary software implementation of the PGP standard, that GPG may make sense to continue using?
That, or perhaps we can use PGP/GPG if they are meant to be interchangeable, allowing for both to appear when searching docs?
|
Side note for those doomed to try reviewing a major amount of diffs in GitHub for a single PR similar to this PR in nature:
Array.from(document.getElementsByClassName('load-diff-button')).map(button => button.click())Wish GitHub had a Load all diffs button. This took a lot of time to eyeball. Source GitHub conversation where I found the snippet: I've added this, along with some other information, to a gist I'm using for collecting helpful snippets like this: |
I'm undecided :) |
Co-authored-by: Derek Ardolf <ScriptAutomate@users.noreply.github.com>
I'm thinking of leaving with egrep -rn "gpgkey|gpg_key"Due to that, and with other docsets such as the GitHub, GitLab, and GitLab seems to use This seems important, because keys will be having @eliasp I'm going to go ahead and apply the commit suggestions I've made for UPDATE: Issue created: #59539 |
GPG revert
GPG revert
GPG revert
GPG revert
GPG revert
GPG revert
What does this PR do?
It cleans up many smaller inconsistencies in the docs, such as:
codein Markdown)Each logical change is a separate commit.
What issues does this PR fix or reference?
None
Merge requirements satisfied?
Commits signed with GPG?
Yes