Add docs and link to technotes.shemyak.com blog post on etree compatibility

Author: kislyuk

README.rst

@@ -14,7 +14,7 @@ payload security in `SAML 2.0 <http://en.wikipedia.org/wiki/SAML_2.0>`_ and
 * Support for exclusive XML canonicalization with inclusive prefixes (`InclusiveNamespaces PrefixList
   <http://www.w3.org/TR/xml-exc-c14n/#def-InclusiveNamespaces-PrefixList>`_, required to verify signatures generated by
   some SAML implementations)
-* Modern Python compatibility (2.7-3.6+ and PyPy)
+* Modern Python compatibility (2.7-3.8+ and PyPy)
 * Well-supported, portable, reliable dependencies: `lxml <https://github.com/lxml/lxml>`_, `defusedxml
   <https://bitbucket.org/tiran/defusedxml>`_, `cryptography <https://github.com/pyca/cryptography>`_, `eight
   <https://github.com/kislyuk/eight>`_, `pyOpenSSL <https://github.com/pyca/pyopenssl>`_
@@ -53,18 +53,28 @@ Note: SignXML depends on `lxml <https://github.com/lxml/lxml>`_ and `cryptograph
 Synopsis
 --------
 
-SignXML uses the ElementTree API (also supported by lxml) to work with XML data.
+SignXML uses the `lxml ElementTree API <https://lxml.de/tutorial.html>`_ to work with XML data. See the
+*Compatibility with xml.etree.ElementTree* section below for some subtle differences.
 
 .. code-block:: python
 
+    from lxml import etree
     from signxml import XMLSigner, XMLVerifier
 
-    cert = open("example.pem").read()
-    key = open("example.key").read()
-    root = ElementTree.fromstring(data_to_sign)
+    data_to_sign = "<Test/>"
+    cert = open("example.pem", "rb").read()
+    key = open("example.key", "rb").read()
+    root = etree.fromstring(data_to_sign)
     signed_root = XMLSigner().sign(root, key=key, cert=cert)
     verified_data = XMLVerifier().verify(signed_root).signed_xml
 
+To make this example self-sufficient for test purposes:
+
+- Generate a test certificate and key using
+  ``openssl req -x509 -sha256 -nodes -subj "/CN=test" -days 1 -newkey rsa:2048 -keyout example.key -out example.pem``.
+- Pass the ``x509_cert=cert`` keyword argument to ``XMLVerifier.verify()``. (In production, ensure this is replaced with
+  the correct configuration for the trusted CA or certificate - this determines which signatures your software trusts.)
+
 .. _verifying-saml-assertions:
 
 Verifying SAML assertions
@@ -131,6 +141,14 @@ For detached signatures, the code above will use the ``Id`` or ``ID`` attribute
 
 See the `API documentation <https://signxml.readthedocs.io/en/latest/#id4>`_ for more.
 
+Compatibility with ``xml.etree.ElementTree``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SignXML uses the `lxml <https://github.com/lxml/lxml>`_ ElementTree library, not the
+`ElementTree from Python's standard library <https://docs.python.org/3.8/library/xml.etree.elementtree.html>`_,
+to work with XML. lxml is used due to its XML canonicalization and namespace organization features. Using SignXML
+with ``xml.etree.ElementTree`` is possible, but care must be taken to work around some of its namespace manipulation
+issues, as covered in `this blog post <https://technotes.shemyak.com/posts/xml-signatures-with-python-elementtree/>`_.
+
 Authors
 -------
 * Andrey Kislyuk