From 0989edde0c84caeeffa1743fa920518531785165 Mon Sep 17 00:00:00 2001
From: Lukas Puehringer <lukas.puehringer@nyu.edu>
Date: Fri, 18 Aug 2023 13:39:53 +0200
Subject: [PATCH] doc: add basic Signer API overview to RTD docs

Signed-off-by: Lukas Puehringer <lukas.puehringer@nyu.edu>
---
 docs/index.rst  | 11 +++++++++++
 docs/signer.rst | 21 +++++++++++++++++++++
 2 files changed, 32 insertions(+)
 create mode 100644 docs/signer.rst

diff --git a/docs/index.rst b/docs/index.rst
index 5aa8e083..651a5c68 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,6 +1,17 @@
 Welcome to ``securesystemslib``
 ===============================
 
+A cryptography interface to sign and verify `TUF
+<https://theupdateframework.io>`_ and `in-toto <https://in-toto.io>`_ metadata.
+
+.. note::
+   This documentation is built for
+   `securesystemslib (Python) <https://github.com/secure-systems-lab/securesystemslib>`_, used by
+   `python-tuf <https://github.com/theupdateframework/python-tuf/>`_ and
+   `in-toto (Python) <https://github.com/in-toto/in-toto>`_ reference implementations.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents
+
+   signer
diff --git a/docs/signer.rst b/docs/signer.rst
new file mode 100644
index 00000000..316b880a
--- /dev/null
+++ b/docs/signer.rst
@@ -0,0 +1,21 @@
+Signer API
+==========
+
+.. currentmodule:: securesystemslib.signer
+
+.. warning::
+   The API is experimental and may change without warning in versions ``<1.0.0``.
+
+   See `'New Signer API' <https://theupdateframework.github.io/python-tuf/2023/01/24/securesystemslib-signer-api.html>`_ blog post
+   for background infos.
+
+
+.. Autodoc cannot resolve docs for imported globals (sphinx-doc/sphinx#6495)
+.. As workaround we reference their original internal definition.
+.. autodata:: securesystemslib.signer._signer.SIGNER_FOR_URI_SCHEME
+   :no-value:
+.. autodata:: securesystemslib.signer._key.KEY_FOR_TYPE_AND_SCHEME
+   :no-value:
+.. autoclass:: securesystemslib.signer.Signer
+.. autoclass:: securesystemslib.signer.Key
+.. autoclass:: securesystemslib.signer.Signature