python: post installer docs fix script

* Moved post_installer.py into the examples/howto/ directory.
* Added instructions for its use to the Python Bindings HOWTO.
* Ran it as intended from the lang/python/ directory in order to both
  prove it works and quickly and easily get the updated howto
  replicated.  Also to fix all those .texi files.

Tested-by: Ben McGinnes <ben@adversary.org>
Signed-off-by: Ben McGinnes <ben@adversary.org>

lang/python/doc/rst/gpgme-python-howto.rst

@@ -683,6 +683,21 @@ on the system and version of Python in use. Another option is to run the
 command ``python3 -m virtualenv /path/to/install/virtual/thingy``
 instead.
 
+.. _snafu-docs:
+
+Post installation
+~~~~~~~~~~~~~~~~~
+
+Following installation it is recommended to move the
+``post_installer.py`` script from the ``lang/python/examples/howto/``
+directory to the ``lang/python/`` directory and run it. This will fix or
+restore files needed by Sphinx which may be removed during a
+distribution build for release. It will also generate reST files from
+Org mode files with Pandoc and generate Texinfo files from Org mode
+files with GNU Emacs and Org mode (in batch mode). Additionally it will
+fix the UTF-8 declaration line in the Texinfo files (Emacs expects
+\"UTF-8\" to be \"utf-8\").
+
 .. _howto-fund-a-mental:
 
 Fundamentals

lang/python/doc/rst/index.rst

@@ -7,7 +7,7 @@ GPGME Python Bindings
 =====================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
 Contents
@@ -20,11 +20,3 @@ Contents
 
 -  `What Was New <what-was-new>`__
 -  `GPGME Python Bindings HOWTO <gpgme-python-howto>`__
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

lang/python/doc/src/gpgme-python-howto

@@ -705,6 +705,22 @@ the command =python3 -m virtualenv /path/to/install/virtual/thingy=
 instead.
 
 
+*** Post installation
+    :PROPERTIES:
+    :CUSTOM_ID: snafu-docs
+    :END:
+
+Following installation it is recommended to move the
+=post_installer.py= script from the =lang/python/examples/howto/=
+directory to the =lang/python/= directory and run it.  This will fix
+or restore files needed by Sphinx which may be removed during a
+distribution build for release.  It will also generate reST files from
+Org mode files with Pandoc and generate Texinfo files from Org mode
+files with GNU Emacs and Org mode (in batch mode).  Additionally it
+will fix the UTF-8 declaration line in the Texinfo files (Emacs
+expects "UTF-8" to be "utf-8").
+
+
 * Fundamentals
   :PROPERTIES:
   :CUSTOM_ID: howto-fund-a-mental

lang/python/doc/texinfo/gpgme-python-howto.texi

@@ -81,6 +81,7 @@ Known Issues
 * Won't Work With Windows::
 * CFFI is the Best™ and GPGME should use it instead of SWIG::
 * Virtualised Environments::
+* Post installation::
 
 Fundamentals
 
@@ -511,6 +512,7 @@ they be encountered.
 * Won't Work With Windows::
 * CFFI is the Best™ and GPGME should use it instead of SWIG::
 * Virtualised Environments::
+* Post installation::
 @end menu
 
 @node Breaking Builds
@@ -883,6 +885,19 @@ on the system and version of Python in use.  Another option is to run
 the command @samp{python3 -m virtualenv /path/to/install/virtual/thingy}
 instead.
 
+@node Post installation
+@subsection Post installation
+
+Following installation it is recommended to move the
+@samp{post_installer.py} script from the @samp{lang/python/examples/howto/}
+directory to the @samp{lang/python/} directory and run it.  This will fix
+or restore files needed by Sphinx which may be removed during a
+distribution build for release.  It will also generate reST files from
+Org mode files with Pandoc and generate Texinfo files from Org mode
+files with GNU Emacs and Org mode (in batch mode).  Additionally it
+will fix the UTF-8 declaration line in the Texinfo files (Emacs
+expects "UTF-8" to be "utf-8").
+
 @node Fundamentals
 @chapter Fundamentals