From e32beb58451eb917616ac9d91058d0dffc04ee2b Mon Sep 17 00:00:00 2001 From: Teodora Sechkova Date: Mon, 9 Aug 2021 15:23:54 +0300 Subject: [PATCH 01/12] Add sphinx docs source files Add .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. The following command will generate the documentation from the source files in an html format: `sphinx-build -b html docs/sphinx/source docs/sphinx/build/html` Signed-off-by: Teodora Sechkova --- docs/sphinx/source/conf.py | 57 ++++++++++++++++++++ docs/sphinx/source/index.rst | 19 +++++++ docs/sphinx/source/legacy-implementation.rst | 10 ++++ docs/sphinx/source/modern-implementation.rst | 31 +++++++++++ docs/sphinx/source/tuf.api.metadata.rst | 7 +++ docs/sphinx/source/tuf.api.rst | 10 ++++ docs/sphinx/source/tuf.api.serialization.rst | 11 ++++ docs/sphinx/source/tuf.ngclient.config.rst | 8 +++ docs/sphinx/source/tuf.ngclient.fetcher.rst | 10 ++++ docs/sphinx/source/tuf.ngclient.rst | 10 ++++ docs/sphinx/source/tuf.ngclient.updater.rst | 8 +++ 11 files changed, 181 insertions(+) create mode 100644 docs/sphinx/source/conf.py create mode 100644 docs/sphinx/source/index.rst create mode 100644 docs/sphinx/source/legacy-implementation.rst create mode 100644 docs/sphinx/source/modern-implementation.rst create mode 100644 docs/sphinx/source/tuf.api.metadata.rst create mode 100644 docs/sphinx/source/tuf.api.rst create mode 100644 docs/sphinx/source/tuf.api.serialization.rst create mode 100644 docs/sphinx/source/tuf.ngclient.config.rst create mode 100644 docs/sphinx/source/tuf.ngclient.fetcher.rst create mode 100644 docs/sphinx/source/tuf.ngclient.rst create mode 100644 docs/sphinx/source/tuf.ngclient.updater.rst diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py new file mode 100644 index 0000000000..935ff9f1ec --- /dev/null +++ b/docs/sphinx/source/conf.py @@ -0,0 +1,57 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..'))) + +import tuf + +# -- Project information ----------------------------------------------------- + +project = 'TUF' +copyright = '2021, New York University and the TUF contributors' +author = 'New York University and the TUF contributors' + + +# -- General configuration --------------------------------------------------- + +master_doc = 'index' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.napoleon'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +autodoc_mock_imports = ['securesystemslib'] + diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst new file mode 100644 index 0000000000..39fcd96286 --- /dev/null +++ b/docs/sphinx/source/index.rst @@ -0,0 +1,19 @@ +Welcome to TUF's documentation! +=============================== + +This is the documentation of the **reference implementation** of +`The Update Framework (TUF) `_. + +The reference implementation strives to be a readable guide and demonstration +for those working on implementing TUF in their own languages, environments, or +update systems. It is written in Python and intended to conform to version 1.0 of the +`TUF specification `_. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + modern-implementation + legacy-implementation + diff --git a/docs/sphinx/source/legacy-implementation.rst b/docs/sphinx/source/legacy-implementation.rst new file mode 100644 index 0000000000..87c7ce93fe --- /dev/null +++ b/docs/sphinx/source/legacy-implementation.rst @@ -0,0 +1,10 @@ +Legacy implementation +===================== + +.. note:: The legacy implementation, with + `tuf/client/updater.py `_ implementing the detailed + client workflow and `tuf/repository_tool.py `_ + providing a high-level interface for repository operations, is in use in production systems, but is `no longer + being actively worked on `_. + + diff --git a/docs/sphinx/source/modern-implementation.rst b/docs/sphinx/source/modern-implementation.rst new file mode 100644 index 0000000000..7d96db3149 --- /dev/null +++ b/docs/sphinx/source/modern-implementation.rst @@ -0,0 +1,31 @@ +Modern implementation +===================== + +The reference implementation is being refactored using +`modern Python `_ +to both: + +* Address scalability and integration issues identified in supporting integration + into the Python Package Index (PyPI), and other large-scale repositories. +* Ensure maintainability of the project. + +This implementation consists of: + +* a "low-level" metadata API, designed to provide easy and safe access to + TUF metadata and handle (de)serialization from/to files, provided in the + :doc:`tuf.api` module. + +* an implementation of the detailed client workflow built on top of the + metadata API, provided in the :doc:`tuf.ngclient` module. + +.. note:: The modern implementation is not considered production ready and + does not yet provide any high-level support for implementing + `repository operations `_, + though the addition of API to support them is planned. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + tuf.api + tuf.ngclient \ No newline at end of file diff --git a/docs/sphinx/source/tuf.api.metadata.rst b/docs/sphinx/source/tuf.api.metadata.rst new file mode 100644 index 0000000000..4d67819743 --- /dev/null +++ b/docs/sphinx/source/tuf.api.metadata.rst @@ -0,0 +1,7 @@ +Metadata API +--------------------------------- + +.. automodule:: tuf.api.metadata + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/sphinx/source/tuf.api.rst b/docs/sphinx/source/tuf.api.rst new file mode 100644 index 0000000000..cbe17e40cb --- /dev/null +++ b/docs/sphinx/source/tuf.api.rst @@ -0,0 +1,10 @@ +Metadata API +=============== + +.. toctree:: + :maxdepth: 4 + + tuf.api.serialization + tuf.api.metadata + + diff --git a/docs/sphinx/source/tuf.api.serialization.rst b/docs/sphinx/source/tuf.api.serialization.rst new file mode 100644 index 0000000000..671b83d5a0 --- /dev/null +++ b/docs/sphinx/source/tuf.api.serialization.rst @@ -0,0 +1,11 @@ +Serialization +============================= + +JSON serialization +----------------------------- + +.. automodule:: tuf.api.serialization.json + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx/source/tuf.ngclient.config.rst b/docs/sphinx/source/tuf.ngclient.config.rst new file mode 100644 index 0000000000..52c46f8e0f --- /dev/null +++ b/docs/sphinx/source/tuf.ngclient.config.rst @@ -0,0 +1,8 @@ +Configuration +============= + +.. automodule:: tuf.ngclient.config + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/sphinx/source/tuf.ngclient.fetcher.rst b/docs/sphinx/source/tuf.ngclient.fetcher.rst new file mode 100644 index 0000000000..c842c47bab --- /dev/null +++ b/docs/sphinx/source/tuf.ngclient.fetcher.rst @@ -0,0 +1,10 @@ +Fetcher +============ + +.. automodule:: tuf.ngclient.fetcher + :members: + :undoc-members: + :show-inheritance: + + + diff --git a/docs/sphinx/source/tuf.ngclient.rst b/docs/sphinx/source/tuf.ngclient.rst new file mode 100644 index 0000000000..b9cb2b356f --- /dev/null +++ b/docs/sphinx/source/tuf.ngclient.rst @@ -0,0 +1,10 @@ +Client API +========== + +.. toctree:: + :maxdepth: 4 + + tuf.ngclient.updater + tuf.ngclient.config + tuf.ngclient.fetcher + diff --git a/docs/sphinx/source/tuf.ngclient.updater.rst b/docs/sphinx/source/tuf.ngclient.updater.rst new file mode 100644 index 0000000000..84e52b9b9e --- /dev/null +++ b/docs/sphinx/source/tuf.ngclient.updater.rst @@ -0,0 +1,8 @@ +Updater +========= + +.. automodule:: tuf.ngclient.updater + :members: + :undoc-members: + :show-inheritance: + From 180fd6392789f5a7c8a534b22f1dc1d53ddf2a1d Mon Sep 17 00:00:00 2001 From: Teodora Sechkova Date: Mon, 9 Aug 2021 15:47:47 +0300 Subject: [PATCH 02/12] Add tox:docs environment - New 'docs' environment in tox enables building the sphinx documentation in isolation. - New requirements-docs.txt. Signed-off-by: Teodora Sechkova --- requirements-docs.txt | 14 ++++++++++++++ tox.ini | 8 ++++++++ 2 files changed, 22 insertions(+) create mode 100644 requirements-docs.txt diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000000..2c2d6e97a9 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,14 @@ +# Install requirements needed in for the documentation build + +# pinned tuf runtime dependencies (should auto-update and -trigger ci/cd) +-r requirements-pinned.txt + +# install sphinx and its extensions +sphinx +sphinx-rtd-theme + +# Docutils versions >=0.17.0 have incompatibilites with +# sphinx-rtd-theme and fail to render some features. +# Pin the version until readthedocs release their fix +# (readthedocs/sphinx_rtd_theme#1113). +docutils<0.17.0 diff --git a/tox.ini b/tox.ini index 0334040e29..75d2117c41 100644 --- a/tox.ini +++ b/tox.ini @@ -54,3 +54,11 @@ commands = mypy bandit -r tuf + +[testenv:docs] +deps = + -r{toxinidir}/requirements-docs.txt + +changedir = {toxinidir} +commands = + sphinx-build -b html docs/sphinx/source docs/sphinx/build/html From ae0e8bab121a7badfa744f4d4a4a0170491bab53 Mon Sep 17 00:00:00 2001 From: Teodora Sechkova Date: Mon, 9 Aug 2021 15:51:03 +0300 Subject: [PATCH 03/12] Add docs/sphinx/build to .gitignore Signed-off-by: Teodora Sechkova --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 9d0648062f..d3590f0f20 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,9 @@ dist/* build/* env/* +# docs build directory +docs/sphinx/build/* + # global file patterns *.log *.pyc From d1329762b638f165d84edad2528cae63bd4f953e Mon Sep 17 00:00:00 2001 From: Teodora Sechkova Date: Mon, 9 Aug 2021 16:08:25 +0300 Subject: [PATCH 04/12] Fix sphinx-build warnings Fix docstrings which triggered warnings from sphinx-build. Signed-off-by: Teodora Sechkova --- tuf/api/metadata.py | 1 + tuf/ngclient/updater.py | 2 ++ 2 files changed, 3 insertions(+) diff --git a/tuf/api/metadata.py b/tuf/api/metadata.py index bf497fcf88..adc1c85686 100644 --- a/tuf/api/metadata.py +++ b/tuf/api/metadata.py @@ -987,6 +987,7 @@ class DelegatedRole(Role): - paths is set: delegates targets matching any path pattern in paths - path_hash_prefixes is set: delegates targets whose target path hash starts with any of the prefixes in path_hash_prefixes + paths and path_hash_prefixes are mutually exclusive: both cannot be set, at least one of them must be set. diff --git a/tuf/ngclient/updater.py b/tuf/ngclient/updater.py index ec5a852d74..561615932c 100644 --- a/tuf/ngclient/updater.py +++ b/tuf/ngclient/updater.py @@ -20,6 +20,7 @@ * When metadata is up-to-date, targets can be dowloaded. The repository snapshot is consistent so multiple targets can be downloaded without fear of repository content changing. For each target: + * :func:`~tuf.ngclient.updater.Updater.get_one_valid_targetinfo()` is used to find information about a specific target. This will load new targets metadata as needed (from local cache or remote repository). @@ -31,6 +32,7 @@ Below is a simple example of using the Updater to download and verify "file.txt" from a remote repository. The required environment for this example is: + * A webserver running on http://localhost:8000, serving TUF repository metadata at "/tuf-repo/" and targets at "/targets/" * Local metadata directory "~/tufclient/metadata/" is writable and contains From 69c2270cddc2688fe46fa4feb4792f11b0be0c15 Mon Sep 17 00:00:00 2001 From: Teodora Sechkova Date: Wed, 11 Aug 2021 17:35:45 +0300 Subject: [PATCH 05/12] Add .readthedocs.yaml Add a configuration file for Read The Docs. Signed-off-by: Teodora Sechkova --- .readthedocs.yaml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..efe6db56b0 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,19 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation with Sphinx +sphinx: + builder: html + configuration: docs/sphinx/source/conf.py + +# Optionally build your docs in additional formats such as PDF +formats: [] + +# Optionally set the version of Python and requirements required to build your docs +python: + install: + - requirements: requirements-docs.txt From b3869186f0dc4b437ec29bae6d474e6af642d527 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Thu, 19 Aug 2021 16:14:57 +0300 Subject: [PATCH 06/12] docs: API Reference tweaks * Improve content * Make ngclient Updater __init__() visible in docs * Remove "legacy implementation" (except for the note on API stability) Signed-off-by: Jussi Kukkonen --- docs/sphinx/source/api-reference.rst | 33 ++++++++++++++++++++ docs/sphinx/source/index.rst | 24 +++++++------- docs/sphinx/source/legacy-implementation.rst | 10 ------ docs/sphinx/source/modern-implementation.rst | 31 ------------------ docs/sphinx/source/tuf.api.metadata.rst | 2 +- docs/sphinx/source/tuf.ngclient.rst | 4 +-- docs/sphinx/source/tuf.ngclient.updater.rst | 4 +-- 7 files changed, 48 insertions(+), 60 deletions(-) create mode 100644 docs/sphinx/source/api-reference.rst delete mode 100644 docs/sphinx/source/legacy-implementation.rst delete mode 100644 docs/sphinx/source/modern-implementation.rst diff --git a/docs/sphinx/source/api-reference.rst b/docs/sphinx/source/api-reference.rst new file mode 100644 index 0000000000..68fb05410e --- /dev/null +++ b/docs/sphinx/source/api-reference.rst @@ -0,0 +1,33 @@ +API Reference +===================== + + +TUF provides multiple APIs: + + +* The low-level :doc:`tuf.api` provides access to a Metadata file abstraction + that closely follows the TUF specification and the file format: This API + handles de/serialization to and from files and makes it easier to access + and modify metadata content safely. It is purely focused on individual + pieces of Metadata and provides no concepts like "repository" or "update + workflow". + +* The client update workflow is implemented in the :doc:`tuf.ngclient` module: It is + a higher-level API that provides ways to query and download target files + securely, while handling the TUF update workflow behind the scenes. ngclient + is implemented on top of the Metadata API and can be used to implement + various TUF clients with relatively little effort. + +.. note:: Major API changes are unlikely but these APIs are not yet + considered stable, and a higher-level repository operations API is not yet + included. + + There is a legacy implementation in the source code (not covered by this + documentation): it is in maintenance mode and receives no feature work. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + tuf.api + tuf.ngclient \ No newline at end of file diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 39fcd96286..654b378f11 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -1,19 +1,17 @@ -Welcome to TUF's documentation! -=============================== +TUF Developer Documentation +=========================== -This is the documentation of the **reference implementation** of -`The Update Framework (TUF) `_. - -The reference implementation strives to be a readable guide and demonstration -for those working on implementing TUF in their own languages, environments, or -update systems. It is written in Python and intended to conform to version 1.0 of the -`TUF specification `_. +This documentation provides essential information for those developing software +with the `Python reference implementation of The Update Framework (TUF) +`_. +The reference implementation provides easy-to-use components for Python +developers but also aims to be a readable guide and demonstration for those +working on implementing TUF in their own languages, environments, or update +systems. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: - modern-implementation - legacy-implementation - + api-reference diff --git a/docs/sphinx/source/legacy-implementation.rst b/docs/sphinx/source/legacy-implementation.rst deleted file mode 100644 index 87c7ce93fe..0000000000 --- a/docs/sphinx/source/legacy-implementation.rst +++ /dev/null @@ -1,10 +0,0 @@ -Legacy implementation -===================== - -.. note:: The legacy implementation, with - `tuf/client/updater.py `_ implementing the detailed - client workflow and `tuf/repository_tool.py `_ - providing a high-level interface for repository operations, is in use in production systems, but is `no longer - being actively worked on `_. - - diff --git a/docs/sphinx/source/modern-implementation.rst b/docs/sphinx/source/modern-implementation.rst deleted file mode 100644 index 7d96db3149..0000000000 --- a/docs/sphinx/source/modern-implementation.rst +++ /dev/null @@ -1,31 +0,0 @@ -Modern implementation -===================== - -The reference implementation is being refactored using -`modern Python `_ -to both: - -* Address scalability and integration issues identified in supporting integration - into the Python Package Index (PyPI), and other large-scale repositories. -* Ensure maintainability of the project. - -This implementation consists of: - -* a "low-level" metadata API, designed to provide easy and safe access to - TUF metadata and handle (de)serialization from/to files, provided in the - :doc:`tuf.api` module. - -* an implementation of the detailed client workflow built on top of the - metadata API, provided in the :doc:`tuf.ngclient` module. - -.. note:: The modern implementation is not considered production ready and - does not yet provide any high-level support for implementing - `repository operations `_, - though the addition of API to support them is planned. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - tuf.api - tuf.ngclient \ No newline at end of file diff --git a/docs/sphinx/source/tuf.api.metadata.rst b/docs/sphinx/source/tuf.api.metadata.rst index 4d67819743..03e3ef8722 100644 --- a/docs/sphinx/source/tuf.api.metadata.rst +++ b/docs/sphinx/source/tuf.api.metadata.rst @@ -1,4 +1,4 @@ -Metadata API +Metadata --------------------------------- .. automodule:: tuf.api.metadata diff --git a/docs/sphinx/source/tuf.ngclient.rst b/docs/sphinx/source/tuf.ngclient.rst index b9cb2b356f..3a31edbc92 100644 --- a/docs/sphinx/source/tuf.ngclient.rst +++ b/docs/sphinx/source/tuf.ngclient.rst @@ -1,5 +1,5 @@ -Client API -========== +ngclient +======== .. toctree:: :maxdepth: 4 diff --git a/docs/sphinx/source/tuf.ngclient.updater.rst b/docs/sphinx/source/tuf.ngclient.updater.rst index 84e52b9b9e..0fc46757c9 100644 --- a/docs/sphinx/source/tuf.ngclient.updater.rst +++ b/docs/sphinx/source/tuf.ngclient.updater.rst @@ -3,6 +3,4 @@ Updater .. automodule:: tuf.ngclient.updater :members: - :undoc-members: - :show-inheritance: - + :special-members: __init__ From 3ee6a3e7868799219bec2168d02e74c7a0376997 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Thu, 19 Aug 2021 16:20:41 +0300 Subject: [PATCH 07/12] docs: Tweak INSTALLATION.rst * Remove link to outdated roadmap * Link to maintainers file in the same way as two lines earlier * Fix formatting issues with code blocks These fixes allow the installation rst to be used from sphinx sources and from docs root. Signed-off-by: Jussi Kukkonen --- docs/INSTALLATION.rst | 41 +++++++++++++++++------------------------ 1 file changed, 17 insertions(+), 24 deletions(-) diff --git a/docs/INSTALLATION.rst b/docs/INSTALLATION.rst index a0a4200d7c..cea6b3c3e9 100644 --- a/docs/INSTALLATION.rst +++ b/docs/INSTALLATION.rst @@ -12,19 +12,13 @@ is available on our `website and on the `maintainers page `_. -The latest release and its packaging information, such as who signed the -release and their PGP fingerprint, can also be found on our 1-year `roadmap -`_. - - Release Verification -------------------- -Assuming you trust `the maintainer's PGP key `_, the detached -ASC signature can be downloaded and verified. For example: - -:: +Assuming you trust `the maintainer's PGP key +`_, +the detached ASC signature can be downloaded and verified. For example:: $ gpg --verify securesystemslib-0.10.8.tar.gz.asc gpg: assuming signed data in 'securesystemslib-0.10.8.tar.gz' @@ -42,20 +36,20 @@ installation, done simply with one of the following commands: Installing from Python Package Index (https://pypi.python.org/pypi). (Note: Please use "python3 -m pip install --no-use-wheel tuf" if your version -of pip <= 1.5.6) -:: +of pip <= 1.5.6):: + $ python3 -m pip install tuf **Alternatively**, if you wish to install from a GitHub release you've already downloaded, or a package you obtained in another way, you can instead: -Install from a local source archive: -:: +Install from a local source archive:: + $ python3 -m pip install -Or install from the root directory of the unpacked archive: -:: +Or install from the root directory of the unpacked archive:: + $ python3 -m pip install . @@ -68,8 +62,8 @@ be verified, in pure Python. To fully support RSA, Ed25519, ECDSA, and other crypto, you must install the extra dependencies declared by securesystemslib. **Note**: that may require non-Python dependencies, so if you encounter an error attempting this pip command, see -`more instructions below <#non-python-dependencies>`_). -:: +`more instructions below <#non-python-dependencies>`_). :: + $ python3 -m pip install securesystemslib[crypto,pynacl] tuf @@ -84,17 +78,16 @@ For example, PyNaCl and Cryptography -- two libraries used in the full installation to support certain cryptographic functions -- may require FFI (Foreign Function Interface) development header files. -Debian-based distributions can install the necessary header libraries with apt -(Advanced Package Tool.) -:: +Debian-based distributions can install the necessary header libraries with apt:: + $ apt-get install build-essential libssl-dev libffi-dev python-dev -Fedora-based distributions can instead install these libraries with dnf. -:: +Fedora-based distributions can instead install these libraries with dnf:: + $ dnf install libffi-devel redhat-rpm-config openssl-devel OS X users can install these header libraries with the `Homebrew `_ -package manager, among other options. -:: +package manager, among other options:: + $ brew install python3 $ brew install libffi From 4f71f98008ffdbb89fa2fb9b8c19722d29a8f037 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Fri, 20 Aug 2021 15:52:57 +0300 Subject: [PATCH 08/12] docs: Move the sphinx root to docs/ This allows using existing documentation in the published documentation without * moving the existing docs (which would break external links) * tricks like symlinks that create issues with relative links Put the api reference files into a subdirectory to avoid polluting the main docs/ directory. Include "Installation" and "Instructions for Contributors" in the published documentation. Signed-off-by: Jussi Kukkonen --- .gitignore | 2 +- .readthedocs.yaml | 2 +- docs/{sphinx/source => api}/api-reference.rst | 0 docs/{sphinx/source => api}/tuf.api.metadata.rst | 0 docs/{sphinx/source => api}/tuf.api.rst | 0 docs/{sphinx/source => api}/tuf.api.serialization.rst | 0 docs/{sphinx/source => api}/tuf.ngclient.config.rst | 0 docs/{sphinx/source => api}/tuf.ngclient.fetcher.rst | 0 docs/{sphinx/source => api}/tuf.ngclient.rst | 0 docs/{sphinx/source => api}/tuf.ngclient.updater.rst | 0 docs/{sphinx/source => }/conf.py | 5 ++--- docs/{sphinx/source => }/index.rst | 4 +++- tox.ini | 2 +- 13 files changed, 8 insertions(+), 7 deletions(-) rename docs/{sphinx/source => api}/api-reference.rst (100%) rename docs/{sphinx/source => api}/tuf.api.metadata.rst (100%) rename docs/{sphinx/source => api}/tuf.api.rst (100%) rename docs/{sphinx/source => api}/tuf.api.serialization.rst (100%) rename docs/{sphinx/source => api}/tuf.ngclient.config.rst (100%) rename docs/{sphinx/source => api}/tuf.ngclient.fetcher.rst (100%) rename docs/{sphinx/source => api}/tuf.ngclient.rst (100%) rename docs/{sphinx/source => api}/tuf.ngclient.updater.rst (100%) rename docs/{sphinx/source => }/conf.py (93%) rename docs/{sphinx/source => }/index.rst (91%) diff --git a/.gitignore b/.gitignore index d3590f0f20..e988195f05 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,7 @@ build/* env/* # docs build directory -docs/sphinx/build/* +docs/build/* # global file patterns *.log diff --git a/.readthedocs.yaml b/.readthedocs.yaml index efe6db56b0..58dec99503 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -8,7 +8,7 @@ version: 2 # Build documentation with Sphinx sphinx: builder: html - configuration: docs/sphinx/source/conf.py + configuration: docs/conf.py # Optionally build your docs in additional formats such as PDF formats: [] diff --git a/docs/sphinx/source/api-reference.rst b/docs/api/api-reference.rst similarity index 100% rename from docs/sphinx/source/api-reference.rst rename to docs/api/api-reference.rst diff --git a/docs/sphinx/source/tuf.api.metadata.rst b/docs/api/tuf.api.metadata.rst similarity index 100% rename from docs/sphinx/source/tuf.api.metadata.rst rename to docs/api/tuf.api.metadata.rst diff --git a/docs/sphinx/source/tuf.api.rst b/docs/api/tuf.api.rst similarity index 100% rename from docs/sphinx/source/tuf.api.rst rename to docs/api/tuf.api.rst diff --git a/docs/sphinx/source/tuf.api.serialization.rst b/docs/api/tuf.api.serialization.rst similarity index 100% rename from docs/sphinx/source/tuf.api.serialization.rst rename to docs/api/tuf.api.serialization.rst diff --git a/docs/sphinx/source/tuf.ngclient.config.rst b/docs/api/tuf.ngclient.config.rst similarity index 100% rename from docs/sphinx/source/tuf.ngclient.config.rst rename to docs/api/tuf.ngclient.config.rst diff --git a/docs/sphinx/source/tuf.ngclient.fetcher.rst b/docs/api/tuf.ngclient.fetcher.rst similarity index 100% rename from docs/sphinx/source/tuf.ngclient.fetcher.rst rename to docs/api/tuf.ngclient.fetcher.rst diff --git a/docs/sphinx/source/tuf.ngclient.rst b/docs/api/tuf.ngclient.rst similarity index 100% rename from docs/sphinx/source/tuf.ngclient.rst rename to docs/api/tuf.ngclient.rst diff --git a/docs/sphinx/source/tuf.ngclient.updater.rst b/docs/api/tuf.ngclient.updater.rst similarity index 100% rename from docs/sphinx/source/tuf.ngclient.updater.rst rename to docs/api/tuf.ngclient.updater.rst diff --git a/docs/sphinx/source/conf.py b/docs/conf.py similarity index 93% rename from docs/sphinx/source/conf.py rename to docs/conf.py index 935ff9f1ec..2b0876200b 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/conf.py @@ -12,7 +12,7 @@ # import os import sys -sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..'))) +sys.path.insert(0, os.path.abspath(os.path.join('..'))) import tuf @@ -38,8 +38,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - +exclude_patterns = ['GETTING_STARTED.rst', 'OVERVIEW.rst', 'TAP.rst'] # -- Options for HTML output ------------------------------------------------- diff --git a/docs/sphinx/source/index.rst b/docs/index.rst similarity index 91% rename from docs/sphinx/source/index.rst rename to docs/index.rst index 654b378f11..99aaee15f5 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/index.rst @@ -14,4 +14,6 @@ systems. :maxdepth: 1 :caption: Contents: - api-reference + api/api-reference + CONTRIBUTORS + INSTALLATION \ No newline at end of file diff --git a/tox.ini b/tox.ini index 75d2117c41..f7e1d7a5f8 100644 --- a/tox.ini +++ b/tox.ini @@ -61,4 +61,4 @@ deps = changedir = {toxinidir} commands = - sphinx-build -b html docs/sphinx/source docs/sphinx/build/html + sphinx-build -b html docs docs/build/html From 1a714f7dc8ee8b1626def85ec89f682ad1cf88cb Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Mon, 23 Aug 2021 10:34:02 +0300 Subject: [PATCH 09/12] docs: Improve tuf.api docs Write a bit more about the two modules, hide the actual TOC to not repeat (and not have sphinx complain about missing items in TOC) Signed-off-by: Jussi Kukkonen --- docs/api/tuf.api.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/api/tuf.api.rst b/docs/api/tuf.api.rst index cbe17e40cb..72116ec5b2 100644 --- a/docs/api/tuf.api.rst +++ b/docs/api/tuf.api.rst @@ -1,10 +1,13 @@ Metadata API =============== -.. toctree:: - :maxdepth: 4 +The low-level Metadata API contains two modules: - tuf.api.serialization - tuf.api.metadata +* :doc:`tuf.api.metadata` contains the actual Metadata abstraction that higher level libraries and application code should use to interact with TUF metadata. This abstraction provides safe reading and writing to supported file formats and helper functions for accessing and modifying the metadata contents. +* :doc:`tuf.api.serialization` covers serializing the metadata into specific wire formats (like json). +.. toctree:: + :hidden: + tuf.api.metadata + tuf.api.serialization From 657aa3dfd5a19334c8e86b158cbca81590162ad3 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Mon, 23 Aug 2021 10:46:25 +0300 Subject: [PATCH 10/12] docs: Improve ngclient docs Signed-off-by: Jussi Kukkonen --- docs/api/tuf.ngclient.rst | 9 ++++++++- tuf/ngclient/updater.py | 6 +++--- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/api/tuf.ngclient.rst b/docs/api/tuf.ngclient.rst index 3a31edbc92..df705bbf03 100644 --- a/docs/api/tuf.ngclient.rst +++ b/docs/api/tuf.ngclient.rst @@ -1,8 +1,15 @@ ngclient ======== +The ngclient module contains a complete TUF client library implementation. + +* :doc:`tuf.ngclient.updater` implements the client update workflow +* :doc:`tuf.ngclient.config` provides optional configuration for the updater +* :doc:`tuf.ngclient.fetcher` can be used for optional low-level network I/O control + + .. toctree:: - :maxdepth: 4 + :hidden: tuf.ngclient.updater tuf.ngclient.config diff --git a/tuf/ngclient/updater.py b/tuf/ngclient/updater.py index 561615932c..205328159c 100644 --- a/tuf/ngclient/updater.py +++ b/tuf/ngclient/updater.py @@ -1,9 +1,9 @@ # Copyright 2020, New York University and the TUF contributors # SPDX-License-Identifier: MIT OR Apache-2.0 -"""TUF module that implements the client update workflow. +"""Client update workflow implementation -This module contains the Updater class that provides an implementation of the +The Updater class provides an implementation of the `TUF client workflow `_. Updater provides an API to query available targets and to download them in a @@ -37,7 +37,7 @@ metadata at "/tuf-repo/" and targets at "/targets/" * Local metadata directory "~/tufclient/metadata/" is writable and contains a root metadata version for the remote repository - * Download directory "~/target-downloads/" is writable + * Download directory "~/tufclient/downloads/" is writable Example:: From e5de36f4e06b154ea5fa3b931533f7999457eaab Mon Sep 17 00:00:00 2001 From: Teodora Sechkova Date: Wed, 25 Aug 2021 16:59:31 +0300 Subject: [PATCH 11/12] docs: Add links to the specification Signed-off-by: Teodora Sechkova --- docs/api/api-reference.rst | 13 ++++++++----- docs/api/tuf.ngclient.rst | 4 +++- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/api/api-reference.rst b/docs/api/api-reference.rst index 68fb05410e..0c4b17bc05 100644 --- a/docs/api/api-reference.rst +++ b/docs/api/api-reference.rst @@ -6,14 +6,14 @@ TUF provides multiple APIs: * The low-level :doc:`tuf.api` provides access to a Metadata file abstraction - that closely follows the TUF specification and the file format: This API - handles de/serialization to and from files and makes it easier to access + that closely follows the TUF specification's `document formats`_. + This API handles de/serialization to and from files and makes it easier to access and modify metadata content safely. It is purely focused on individual pieces of Metadata and provides no concepts like "repository" or "update workflow". -* The client update workflow is implemented in the :doc:`tuf.ngclient` module: It is - a higher-level API that provides ways to query and download target files +* The `client update workflow`_ is implemented in the :doc:`tuf.ngclient` module: + It is a higher-level API that provides ways to query and download target files securely, while handling the TUF update workflow behind the scenes. ngclient is implemented on top of the Metadata API and can be used to implement various TUF clients with relatively little effort. @@ -30,4 +30,7 @@ TUF provides multiple APIs: :caption: Contents: tuf.api - tuf.ngclient \ No newline at end of file + tuf.ngclient + +.. _client update workflow: https://theupdateframework.github.io/specification/latest/#detailed-client-workflow +.. _document formats: https://theupdateframework.github.io/specification/latest/#document-formats diff --git a/docs/api/tuf.ngclient.rst b/docs/api/tuf.ngclient.rst index df705bbf03..31b7ba7e69 100644 --- a/docs/api/tuf.ngclient.rst +++ b/docs/api/tuf.ngclient.rst @@ -3,7 +3,7 @@ ngclient The ngclient module contains a complete TUF client library implementation. -* :doc:`tuf.ngclient.updater` implements the client update workflow +* :doc:`tuf.ngclient.updater` implements the `detailed client workflow`_ * :doc:`tuf.ngclient.config` provides optional configuration for the updater * :doc:`tuf.ngclient.fetcher` can be used for optional low-level network I/O control @@ -15,3 +15,5 @@ The ngclient module contains a complete TUF client library implementation. tuf.ngclient.config tuf.ngclient.fetcher +.. _detailed client workflow: https://theupdateframework.github.io/specification/latest/#detailed-client-workflow + From 21ff4920ab345f95b30b37ff2862e52e1b74f629 Mon Sep 17 00:00:00 2001 From: Teodora Sechkova Date: Wed, 25 Aug 2021 17:00:05 +0300 Subject: [PATCH 12/12] docs: Improve formating Remove/add new lines at the end of file. Signed-off-by: Teodora Sechkova --- docs/api/tuf.api.metadata.rst | 2 +- docs/api/tuf.api.rst | 9 +++++++-- docs/api/tuf.api.serialization.rst | 1 - docs/api/tuf.ngclient.config.rst | 1 - docs/api/tuf.ngclient.fetcher.rst | 3 --- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/api/tuf.api.metadata.rst b/docs/api/tuf.api.metadata.rst index 03e3ef8722..c4a58bb4e2 100644 --- a/docs/api/tuf.api.metadata.rst +++ b/docs/api/tuf.api.metadata.rst @@ -4,4 +4,4 @@ Metadata .. automodule:: tuf.api.metadata :members: :undoc-members: - :show-inheritance: \ No newline at end of file + :show-inheritance: diff --git a/docs/api/tuf.api.rst b/docs/api/tuf.api.rst index 72116ec5b2..b93902c6bb 100644 --- a/docs/api/tuf.api.rst +++ b/docs/api/tuf.api.rst @@ -3,8 +3,13 @@ Metadata API The low-level Metadata API contains two modules: -* :doc:`tuf.api.metadata` contains the actual Metadata abstraction that higher level libraries and application code should use to interact with TUF metadata. This abstraction provides safe reading and writing to supported file formats and helper functions for accessing and modifying the metadata contents. -* :doc:`tuf.api.serialization` covers serializing the metadata into specific wire formats (like json). +* :doc:`tuf.api.metadata` contains the actual Metadata abstraction + that higher level libraries and application code should use to interact + with TUF metadata. This abstraction provides safe reading and writing to + supported file formats and helper functions for accessing and modifying + the metadata contents. +* :doc:`tuf.api.serialization` covers serializing the metadata into + specific wire formats (like json). .. toctree:: :hidden: diff --git a/docs/api/tuf.api.serialization.rst b/docs/api/tuf.api.serialization.rst index 671b83d5a0..1603148dc6 100644 --- a/docs/api/tuf.api.serialization.rst +++ b/docs/api/tuf.api.serialization.rst @@ -8,4 +8,3 @@ JSON serialization :members: :undoc-members: :show-inheritance: - diff --git a/docs/api/tuf.ngclient.config.rst b/docs/api/tuf.ngclient.config.rst index 52c46f8e0f..150df08273 100644 --- a/docs/api/tuf.ngclient.config.rst +++ b/docs/api/tuf.ngclient.config.rst @@ -5,4 +5,3 @@ Configuration :members: :undoc-members: :show-inheritance: - diff --git a/docs/api/tuf.ngclient.fetcher.rst b/docs/api/tuf.ngclient.fetcher.rst index c842c47bab..1f689d4fd9 100644 --- a/docs/api/tuf.ngclient.fetcher.rst +++ b/docs/api/tuf.ngclient.fetcher.rst @@ -5,6 +5,3 @@ Fetcher :members: :undoc-members: :show-inheritance: - - -