python: docs updates

* Multiple updates, expanding on the Windows installation issues.
* Also adding to the new maintenance mode reference document.
* Includes content relating to the resolution of T4271 and T4191.

Tested-by: Ben McGinnes <[email protected]>
Signed-off-by: Ben McGinnes <[email protected]>

2 files changed, 53 insertions, 3 deletions

diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto
index c6b00027..9820d86b 100644
--- a/lang/python/doc/src/gpgme-python-howto
+++ b/lang/python/doc/src/gpgme-python-howto
@@ -2095,6 +2095,10 @@ content as a byte object, the recipient key IDs and algorithms in
 =result= and the results of verifying any signatures of the data in
 =verify_result=.
 
+If =gpg.Context().decrypt(cfile, verify=False)= is called instead,
+then =verify_result= will be returned as =None= and the rest remains
+as described here.
+
 
 ** Signing text and files
    :PROPERTIES:
@@ -3163,9 +3167,9 @@ Draft editions of this HOWTO may be periodically available directly
 from the author at any of the following URLs:
 
 - [[https://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL)]]
-- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SS)]]
+- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SSL)]]
 - [[https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 SSL)]]
-- [[http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)]]
+- [[http://files.au.adversary.org/crypto/gpgme-python-howto/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)]]
 
 All of these draft versions except for one have been generated from
 this document via GNU Emacs [[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]].  Though it is
@@ -3194,10 +3198,16 @@ commands:
 #+END_SRC
 
 In addition to these there is a significantly less frequently updated
-version as a HTML [[https://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html][WebHelp site]] (AWS S3 SSL); generated from DITA XML
+version as a HTML [[https://files.au.adversary.org/crypto/gpgme-python/dita/webhelp/index.html][WebHelp site]] (AWS S3 SSL); generated from DITA XML
 source files, which can be found in [[https://dev.gnupg.org/source/gpgme/browse/ben%252Fhowto-dita/][an alternative branch]] of the GPGME
 git repository.
 
+Various generated output formats may occasionally be found in
+subdirectories of the [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python][gpgme-python]] directory.  In particular within
+the [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/dita][DITA]], [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/rst][reStructuredText]] and [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/texinfo][Texinfo]] subdirectories.  The =rst=
+directory contains output files generated with Sphix and may include a
+considerable number of its possible output formats.
+
 These draft editions are not official documents and the version of
 documentation in the master branch or which ships with released
 versions is the only official documentation.  Nevertheless, these
diff --git a/lang/python/doc/src/maintenance-mode b/lang/python/doc/src/maintenance-mode
index 48c3d409..4b4e0fca 100644
--- a/lang/python/doc/src/maintenance-mode
+++ b/lang/python/doc/src/maintenance-mode
@@ -93,3 +93,43 @@ basis.  Expediting such a request would require funding that request.
 Those with a commercial interest in expediting such a feature request
 already know how to [[https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset][expedite it]] (use the message field to state what
 feature is being requested).
+
+
+** Documentation formats
+   :PROPERTIES:
+   :CUSTOM_ID: docs
+   :END:
+
+The documentation has been written in Org mode for GNU Emacs, with
+both Texinfo and reStructuredText formats generated from that.  The
+Texinfo files are intended for use with the rest of the GnuPG
+documentation; while the reStructuredText files are intended for use
+with Docutils and Sphinx, as with other Python projects.
+
+
+*** Cautionary Notes regarding Sphinx and EPUB
+    :PROPERTIES:
+    :CUSTOM_ID: sphinx-made-epubs-suck
+    :END:
+
+Though Python's Docutils in conjunction with Sphinx is capable of
+generating some very useful HTML sites, as proven by [[https://readthedocs.org/][Read the Docs]] and
+the [[https://docs.python.org/][Python documentation]], there are a number of output formats it does
+not handle well.  At the top of the list of things it manages to break
+so atrociously as to be embarassing is the [[http://idpf.org/epub][EPUB 3]] format.
+
+The automatically generated EPUB of the CPython documentation always
+contains hundreds of validation errors and even the modest amount of
+documentation here [[https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub][produced a file]] with approximately thirty
+validation errors.  As the volume of documentation content increases,
+so does the induced errors.  Whereas Texinfo doesn't produce EPUB
+output at all, nor does Org-mode.
+
+Should there ever be genuine demand for this format, lodge a [[https://dev.gnupg.org/maniphest/task/edit/form/4/][feature
+request]] case marked for [[https://dev.gnupg.org/p/BenM/][my]] attention.  The means of generating such
+files flawlessly is already available, but is not yet part of the
+GnuPG build system.  Nor is it integrated with a means of converting
+Org mode input files to the relevant base format automatically, as can
+already be done when converting Org to reStructuredText or Org to
+Texinfo.  As a certain amount of work would be required to get it
+done, there would need to be clear demand for that work to be done.