Documentation improvements

Author: kislyuk

.github/ISSUE_TEMPLATE/signxml-issue.md

@@ -15,6 +15,7 @@ Thank you for your interest in signxml. If you want to report an issue or make a
 - If you are looking for general technical help, please ensure you have read and understood the documentation for the software and standards this project builds upon. Issues that don't confirm that effort was taken to check the relevant documentation will be closed.
 - If you wish to report a bug, please provide a single script that yields a complete standalone reproduction of the observed behavior, together with an explanation of the expected behavior and any citations that may be needed to support the expectation. Issues that don't provide this information will be closed.
 - If you wish to make a feature request, please note that the maintainers' time is limited and you are invited to submit a pull request instead. Pull requests are expected to provide clean readable code, unit tests that cover the code and assert on the newly expected behavior, and documentation.
+- If you are looking for support and using this library in a for-profit project, please donate using the "Sponsor" button above. If you are wondering how much to donate, you can use the rule of thumb of $100 per hour spent addressing your issue.
 
 Thank you for contributing. You can delete this text to edit your issue content.
 

NOTICE

@@ -0,0 +1,5 @@
+SignXML is a free open source implementation of the XML Signature and XAdES standards. The SignXML project is staffed by
+volunteers. If you are using this library in a for-profit project, please contribute to SignXML development and
+maintenance using the "Sponsor" button on the SignXML GitHub project page, https://github.com/XML-Security/signxml. If
+you are looking for support with your XML Signature or XAdES based application, please donate and get in touch with
+SignXML developers using the issue tracker on the SignXML project page or the contact information listed in README.rst.

README.rst

@@ -3,10 +3,13 @@ SignXML: XML Signature in Python
 
 *SignXML* is an implementation of the W3C `XML Signature <http://en.wikipedia.org/wiki/XML_Signature>`_ standard in
 Python. This standard (also known as XMLDSig and `RFC 3275 <http://www.ietf.org/rfc/rfc3275.txt>`_) is used to provide
-payload security in `SAML 2.0 <http://en.wikipedia.org/wiki/SAML_2.0>`_ and
-`WS-Security <https://en.wikipedia.org/wiki/WS-Security>`_, among other uses. Two versions of the standard exist
-(`Version 1.1 <http://www.w3.org/TR/xmldsig-core1/>`_ and `Version 2.0 <http://www.w3.org/TR/xmldsig-core2>`_).
-*SignXML* implements all of the required components of the standard, and most recommended ones. Its features are:
+payload security in `SAML 2.0 <http://en.wikipedia.org/wiki/SAML_2.0>`_, `XAdES <https://en.wikipedia.org/wiki/XAdES>`_,
+and `WS-Security <https://en.wikipedia.org/wiki/WS-Security>`_, among other uses. Two versions of the standard are in
+use (`Version 1.1 <http://www.w3.org/TR/xmldsig-core1/>`_, a finalized
+`W3C Recommendation <https://www.w3.org/standards/types#REC>`_, and
+`Version 2.0 <http://www.w3.org/TR/xmldsig-core2>`_, a draft
+`W3C Working Group Note <https://www.w3.org/standards/types#NOTE>`_). *SignXML* implements all of the required components
+of the Version 1.1 standard, and most recommended ones. Its features are:
 
 * Use of a libxml2-based XML parser configured to defend against
   `common XML attacks <https://docs.python.org/3/library/xml.html#xml-vulnerabilities>`_ when verifying signatures
@@ -117,8 +120,8 @@ Assuming ``metadata.xml`` contains SAML metadata for the assertion source:
  subject name that must be in the signing X.509 certificate given by the signature (verified as if it were a
  domain name), or ``ca_pem_file``/``ca_path`` to give a custom CA.
 
-XML signature methods: enveloped, detached, enveloping
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+XML signature construction methods: enveloped, detached, enveloping
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The XML Signature specification defines three ways to compose a signature with the data being signed: enveloped,
 detached, and enveloping signature. Enveloped is the default method. To specify the type of signature that you want to
 generate, pass the ``method`` argument to ``sign()``:
@@ -133,16 +136,16 @@ For detached signatures, the code above will use the ``Id`` or ``ID`` attribute
 ``sign()``. To verify a detached signature that refers to an external entity, pass a callable resolver in
 ``XMLVerifier().verify(data, uri_resolver=...)``.
 
-See the `API documentation <https://xml-security.github.io/signxml/#id5>`_ for more.
+See the `API documentation <https://xml-security.github.io/signxml/#id5>`_ for more details.
 
 
 XML representation details: Configuring namespace prefixes and whitespace
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Some applications require a particular namespace prefix configuration - for example, a number of applications assume
 that the ``http://www.w3.org/2000/09/xmldsig#`` namespace is set as the default, unprefixed namespace instead of using
 the customary ``ds:`` prefix. While in normal use namespace prefix naming is an insignificant representation detail,
-it is significant for XML canonicalization and signature purposes. To configure the namespace prefix map when generating
-a signature, set the ``XMLSigner.namespaces`` attribute:
+it can be significant in some XML canonicalization and signature configurations. To configure the namespace prefix map
+when generating a signature, set the ``XMLSigner.namespaces`` attribute:
 
 .. code-block:: python
 
@@ -171,6 +174,10 @@ references for more information:
 
 XAdES signatures
 ~~~~~~~~~~~~~~~~
+`XAdES ("XML Advanced Electronic Signatures") <https://en.wikipedia.org/wiki/XAdES>`_ is a standard for attaching
+metadata to XML Signature objects. This standard is endorsed by the European Union as the implementation for its
+`eSignature <https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/eSignature+Overview>`_ regulations.
+
 SignXML supports signing and verifying documents using `XAdES <https://en.wikipedia.org/wiki/XAdES>`_ signatures:
 
 .. code-block:: python
@@ -207,7 +214,7 @@ SignXML supports signing and verifying documents using `XAdES <https://en.wikipe
 
 Authors
 -------
-* Andrey Kislyuk
+* `Andrey Kislyuk <https://github.com/kislyuk>`_ and SignXML contributors.
 
 Links
 -----
@@ -233,7 +240,9 @@ Please report bugs, issues, feature requests, etc. on `GitHub <https://github.co
 
 License
 -------
-Licensed under the terms of the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.
+Copyright 2014-2022, Andrey Kislyuk and SignXML contributors. Licensed under the terms of the
+`Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_. Distribution of the LICENSE and NOTICE
+files with source copies of this package and derivative works is **REQUIRED** as specified by the the Apache License.
 
 .. image:: https://github.com/XML-Security/signxml/workflows/Test%20suite/badge.svg
         :target: https://github.com/XML-Security/signxml/actions

signxml/xades/__init__.py

@@ -1,11 +1,13 @@
 """
 `XAdES ("XML Advanced Electronic Signatures") <https://en.wikipedia.org/wiki/XAdES>`_ is a standard for attaching
-metadata to XML Signature objects. The standard is endorsed by the European Union. While a
-`W3C publication from 2003 <https://www.w3.org/TR/XAdES/>`_ exists on the standard, that page is out of date and
-further development was undertaken by `ETSI <https://www.etsi.org>`_. ETSI's approach to standards document publication
-and versioning is best described as idiosyncratic, with many documents produced over time with confusing terminology
-and naming. Documents are only available as PDFs, and there is no apparent way to track all publications on a given
-standard. The most recent and straighforward description of the standard appears to be in the following two documents:
+metadata to XML Signature objects. This standard is endorsed by the European Union as the implementation for its
+`eSignature <https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/eSignature+Overview>`_ regulations.
+While a `W3C publication from 2003 <https://www.w3.org/TR/XAdES/>`_ exists on the standard, that page is out of date
+and further development was undertaken by `ETSI <https://www.etsi.org>`_. ETSI's approach to standards document
+publication and versioning is best described as idiosyncratic, with many documents produced over time with confusing
+terminology and naming. Documents are only available as PDFs, and there is no apparent way to track all publications on
+a given standard. The most recent and straighforward description of the standard appears to be in the following two
+documents:
 
 * `ETSI EN 319 132-1 V1.1.1 (2016-04)
   <https://www.etsi.org/deliver/etsi_en/319100_319199/31913201/01.01.01_60/en_31913201v010101p.pdf>`_,