diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py new file mode 100644 index 00000000..935ff9f1 --- /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 00000000..39fcd962 --- /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 00000000..87c7ce93 --- /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 00000000..7d96db31 --- /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 00000000..4d678197 --- /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 00000000..cbe17e40 --- /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 00000000..671b83d5 --- /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 00000000..52c46f8e --- /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 00000000..c842c47b --- /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 00000000..b9cb2b35 --- /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 00000000..84e52b9b --- /dev/null +++ b/docs/sphinx/source/tuf.ngclient.updater.rst @@ -0,0 +1,8 @@ +Updater +========= + +.. automodule:: tuf.ngclient.updater + :members: + :undoc-members: + :show-inheritance: +