Document experimental reporting API

MatthiasValvekens · Nov 18, 2023 · ff6b23e · ff6b23e
1 parent 786b829
commit ff6b23e
Show file tree

Hide file tree

Showing 5 changed files with 48 additions and 1 deletion.
diff --git a/docs/api-docs/pyhanko.sign.rst b/docs/api-docs/pyhanko.sign.rst
@@ -5,7 +5,7 @@ Subpackages
 -----------
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
 
    pyhanko.sign.ades
    pyhanko.sign.diff_analysis

diff --git a/docs/api-docs/pyhanko.sign.validation.report.rst b/docs/api-docs/pyhanko.sign.validation.report.rst
@@ -0,0 +1,14 @@
+pyhanko.sign.validation.report package
+======================================
+
+
+Submodules
+----------
+
+pyhanko.sign.validation.report.tools module
+-------------------------------------------
+
+.. automodule:: pyhanko.sign.validation.report.tools
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api-docs/pyhanko.sign.validation.rst b/docs/api-docs/pyhanko.sign.validation.rst
@@ -1,6 +1,15 @@
 pyhanko.sign.validation package
 ===============================
 
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   pyhanko.sign.validation.report
+
+
 Submodules
 ----------
 

diff --git a/pyhanko/sign/validation/report/model.py b/pyhanko/sign/validation/report/model.py
diff --git a/pyhanko/sign/validation/report/tools.py b/pyhanko/sign/validation/report/tools.py
@@ -1,3 +1,14 @@
+"""
+ETSI TS 119 102-2 reporting functionality.
+
+.. info:
+    This module requires optional ``[etsi]`` dependency group,
+    and only works on Python 3.8+ for dependency reasons.
+
+.. warning::
+    This feature is incubating and subject to API changes.
+"""
+
 from typing import Any, Dict, Optional, cast
 
 from asn1crypto import tsp
@@ -26,6 +37,8 @@
 from pyhanko.sign.validation.pdf_embedded import EmbeddedPdfSignature
 from pyhanko.sign.validation.status import PdfSignatureStatus
 
+__all__ = ['generate_report']
+
 DIGEST_ALGO_URIS = {
     'sha1': 'http://www.w3.org/2000/09/xmldsig#sha1',
     'sha256': 'http://www.w3.org/2001/04/xmlenc#sha256',
@@ -357,6 +370,17 @@ def _package_validation_object(vo: ValidationObject):
 def generate_report(
     embedded_sig: EmbeddedPdfSignature, status: AdESBasicValidationResult
 ) -> str:
+    """
+    Generate signature validation report in XML format according to
+    ETSI TS 119 102-2.
+
+    :param embedded_sig:
+        PDF signature to report on.
+    :param status:
+        AdES validation result to turn into a report.
+    :return:
+        A string representation of the validation report.
+    """
     report = ts_11910202.ValidationReport(
         signature_validation_report=(_generate_report(embedded_sig, status),),
         signature_validation_objects=ts_11910202.ValidationObjectListType(