theupdateframework
Restructure docs directory
Description of issue or feature request:
Current behavior:
No clear distinction of different documentation types in docs directory.
Expected behavior:
Clear distinction of different documentation types in docs directory, e.g. along the following categories:
- adr
- rtd (e.g. see
sphinx-quickstartdir scaffolding) - misc docs that are neither an adr, nor rendered on rtd (?)
related: see #1848
Related issue: https://github.com/theupdateframework/python-tuf/pull/1853#pullrequestreview-878492917
For background, this is confusing because when RTD docs were created, while the new reference docs were added in a separate docs/api/ we wanted to use the already existing docs in RTD without removing them from easily findable locations in git...
Like the previous link shows this approach does have some problems and maybe it makes sense draw a more strict line between "user documentation" (api reference, installation, examples published on RTD) and internal developer documentation (only in git). It's not always so clear cut though: things like CONTRIBUTORS are edge cases.
Example from pyca/cryptography. In this case they have a
- short GitHub-render-friendly CONTRIBUTING.rst in the canonical location, which just refers to the detailed
- development documentation on RTD