Enable docs build with sphinx

[sechkova]

Fixes #1482

Description of the changes being introduced by the pull request:

• Adds .rst source files for building documentation with sphinx. The two mandatory files are conf.py containing the build configuration and the master doc file index.rst.
• Sphinx uses autodoc to automatically include docstrings. autodoc imports the modules and needs TUF installed in the environment.
• Adds a tox environment for the docs build
• Adds a CI build

The following command will generate the documentation from the source files in an html format:
tox -e docs
or it can be build manually in an environment with TUF installed with:
sphinx-build -b html docs/sphinx/source docs/sphinx/build/html

Configuring a build with sphinx is enough for the documentation to be imported built and published on readthedocs.
This would require a readthedocs account for the project which can be further configured from the UI and a .readthedocs.yaml file.
This is a demo project that I have created from my fork and this PR's branch:
https://tuf-sechkova.readthedocs.io/en/latest/

Please verify and check that the pull request fulfills the following
requirements:

• The code follows the Code Style Guidelines
• Tests have been added for the bug fix or new feature
• Docs have been added for the bug fix or new feature

[jku]

• Adds a CI build

What's the advantage? Can the build fail somehow?

[sechkova]

• Adds a CI build

What's the advantage? Can the build fail somehow?

It can fail in case of wrong configuration (cannot resolve paths to modules, dependencies etc.)
I was actually expecting the build to fail in case of wrong directives or syntax but it only outputs warnings by default. So we can set a flag (- W) to treat warnings as errors unless this feels too strict? Docs are generated anyway in case of warnings, they need to be checked visually if something wasn't rendered correctly.

[sechkova]

After discussing with @jku, I created this readthedocs project linked to TUF's github page and added us both as maintainers: https://theupdateframework.readthedocs.io/en/latest/
Next steps for publishing the documentation would be:

• organization-level access needed by readthedocs OAuth App (which I requested through github, so someone already has a mail in their inbox) .
• configuring the project (.readthedocs.yaml to replace the UI settings). c65b299
• adding additional maintainers

[jku]

Reviewing documentation like this is really difficult... I've left some comments now, not sure how useful.

I think the build changes look ok, but I'm not convinced the CI addition is useful: as you said the doc changes almost always need a human reviewer, it's not really possible to "test them in CI" -- I'd love to get docs generated per PR so they could be reviewed but that's probably asking a lot.

[jku]

Spent a moment thinking about the top-level documentation. I think as a short/mid term goal our top level page should have these links:

• API Reference (this PR mostly)
• Installation (use current INSTALLATION.rst?)
• Getting Started (a document that uses example code from docs: tutorial/example for ngclient Updater #1518, similar to current QUICKSTART.md)
• Contribution Guidelines (use current CONTRIBUTORS.rst?)

[joshuagl]

• organization-level access needed by readthedocs OAuth App (which I requested through github, so someone already has a mail in their inbox) .

Granted.

[jku]

this is still missing the __init__() docs (this is some sphinx thing where it thinks classes only have class or init documentation). autoclass_content = 'both' may work

[jku]

I've worked on this branch at https://github.com/jku/tuf/tree/configure-sphinx:

• some content improvements
• moved the sphinx root to docs/ (to be able to use the existing docs in the published ones)
• included "Installation" and "Instructions for Contributors" in the sphinx documentation.
• mostly removed mentions of "modern implementation" and "legacy implementation": just talk about the API we have

I plan on having a final look through the content and then making a PR (or if teodora is back by then letting her merge my changes to this branch)

[sechkova]

Force pushed the additional commits from @jku's branch + the CI step commit is now removed.

[sechkova]

Rebased to get the pylint fix from develop.

[jku]

LGTM but since half of it is my work maybe someone else should approve as well :)

Let's try to get the readthedocs PR build working before merging (so it would be easier to review the work), but in case that doesn't happen building locally is easy:
tox -e docs
docs/build/html now contains the html docs

EDIT: readthedocs build now works: see list of checks below

[joshuagl]

This is a really great start, nice work @sechkova and @jku.

I left several comments in-line. I don't mind if we address these here or in a future PR, but please update the comments here to indicate which.

[joshuagl]

While we are editing this document, should we change this example to be a tuf release and an active maintainer?

[jku]

this one is from last release

$ gpg --verify tuf-0.17.0.tar.gz.asc 
gpg: assuming signed data in 'tuf-0.17.0.tar.gz'
gpg: Signature made Thu 25 Feb 2021 13:42:50 EET
gpg:                using RSA key 08F3409FCF71D87E30FBD3C21671F65CB74832A4
gpg: Good signature from "Joshua Lock (GPG on YubiKey) <[email protected]>" [unknown]

it does unfortunately continue with

gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 08F3 409F CF71 D87E 30FB  D3C2 1671 F65C B748 32A4

even though I fully trust your key. I hate gpg

[joshuagl]

😩

This was probably scope creep for this PR anyway.

[joshuagl]

should we mention the default fetcher implementation and be more explicit about when users might want to implement this interface?

[sechkova]

I will add this to another issue for further improving the documentation -> #1543

[sechkova]

Closing to test RTD webhooks.

[jku]

Let's see what happens 🤞