doc: update installation documentation #1853
Conversation
Update severely outdated installation documentation. - Simplify "Simple Installation" section - Update "Release Verification" section to actually verify a tuf release and with a key of an active maintainer - Update and simplify section about non-python dependencies (just point to installation instructions for underlying crypto backends, they are up-to-date and have become a lot easier) - Add "Development installation" section Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Replace custom installation section in contribution docs with pointer to updated installation documentation. Also configure sphinx autosectionlabel for cross-document refs. Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Make contributing document header sentence case for consistency with other docs and shorten menu name in side navbar to stand out less. Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
Pull Request Test Coverage Report for Build 1822869441
💛 - Coveralls |
docs/INSTALLATION.rst
Outdated
|
|
||
| Verify release signatures | ||
| ------------------------- |
There was a problem hiding this comment.
I find this section sticking out a bit too much for installation instructions. Should we shorten it, or at least move it to the bottom of the document?
There was a problem hiding this comment.
I think I agree. I'd like to promote signature verification but when the process looks like this (even while handwaving the PGP key lookup part)... I think it breaks the flow of the document and hides the other install options below the fold.
Considering we have three different install methods (normal, native crypto, dev)... maybe list those three first and then verification as the last thing?
|
See https://theupdateframework--1853.org.readthedocs.build/en/1853/INSTALLATION.html for how the docs look on RTD. |
docs/CONTRIBUTING.rst
Outdated
|
|
||
| Also see :ref:`development installation instructions <installation:Install for development>`. |
There was a problem hiding this comment.
This reference is not resolved when the rendered document is browsed on GitHub, which is likely to happen because it is the community standard location for a GitHub repo's contributing docs.
A quick fix would be to use the absolute RTD link (see #1781 (comment)).
In the future we might want to think about separating docs for RTD and docs for GitHub (see #1849)
There was a problem hiding this comment.
yeah, it does look like sharing docs is tricky and results in issues like this.
docs/INSTALLATION.rst
Outdated
|
|
||
| Verify release signatures | ||
| ------------------------- |
There was a problem hiding this comment.
I think I agree. I'd like to promote signature verification but when the process looks like this (even while handwaving the PGP key lookup part)... I think it breaks the flow of the document and hides the other install options below the fold.
Considering we have three different install methods (normal, native crypto, dev)... maybe list those three first and then verification as the last thing?
Move release signature verification instructions to bottom of install docs. The doc is short, so the section is still prominent enough for promoting verification, but does not break the reading flow as much anymore. Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
This is an ugly hack to also resolve the link when the document is rendered in GitHub, where it is likely to be browsed, because it is the community standard location for a GitHub repo's contributing docs. Coordinate with theupdateframework#1849 to better separate RTD docs with GitHub docs in the future. Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
|
@jku, want to take another look at my latest changes? Or should we just merge? |
Fixes #1846
Description of the changes being introduced by the pull request:
Update severely outdated installation documentation.
This PR also updates the install section in the contributing doc, plus other small fixes. See commits for details!
Please verify and check that the pull request fulfills the following
requirements: