Merge branch 'ben/python-docs-01'

* Documentation and the first brush strokes towards the future.

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

4 files changed, 316 insertions, 80 deletions

diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org
new file mode 100644
index 00000000..f684f0a7
--- /dev/null
+++ b/lang/python/docs/Short_History.org
@@ -0,0 +1,172 @@
+#+TITLE: A Short History of the GPGME bindings for Python
+#+LATEX_COMPILER: xelatex
+#+LATEX_CLASS: article
+#+LATEX_CLASS_OPTIONS: [12pt]
+#+LATEX_HEADER: \usepackage{xltxtra}
+#+LATEX_HEADER: \usepackage[margin=1in]{geometry}
+#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Latin Modern Roman}
+
+* Overview
+  :PROPERTIES:
+  :CUSTOM_ID: overview
+  :END:
+
+The GPGME Python bindings passed through many hands and numerous
+phases before, after a fifteen year journey, coming full circle to
+return to the source.  This is a short explanation of that journey.
+
+** In the beginning
+   :PROPERTIES:
+   :CUSTOM_ID: in-the-begining
+   :END:
+
+   In 2002 John Goerzen released PyME; Python bindings for the GPGME
+   module which utilised the current release of Python of the time and
+   SWIG.[fn:1]  Shortly after creating it and ensuring it worked he stopped
+   supporting it, though he left his work available on his Gopher
+   site.
+
+** Keeping the flame alive
+   :PROPERTIES:
+   :CUSTOM_ID: keeping-the-flame-alive
+   :END:
+
+   A couple of years later the project was picked up by Igor Belyi and
+   actively developed and maintained by him from 2004 to 2008.  Igor's
+   whereabouts at the time of this document's creation are unknown,
+   but the current authors do hope he is well.  We're assuming (or
+   hoping) that life did what life does and made continuing untenable.
+
+** Passing the torch
+   :PROPERTIES:
+   :CUSTOM_ID: passing-the-torch
+   :END:
+
+   In 2014 Martin Albrecht wanted to patch a bug in the PyME code and
+   discovered the absence of Igor.  Following a discussion on the PyME
+   mailing list he became the new maintainer for PyME, releasing
+   version 0.9.0 in May of that year.  He remains the maintainer of
+   the original PyME release in Python 2.6 and 2.7 (available via
+   PyPI).
+
+** Coming full circle
+   :PROPERTIES:
+   :CUSTOM_ID: ouroboros 
+   :END:
+
+   In 2015 Ben McGinnes approached Martin about a Python 3 version,
+   while investigating how complex a task this would be the task ended
+   up being completed.  A subsequent discussion with Werner Koch led
+   to the decision to fold the Python 3 port back into the original
+   GPGME release in the languages subdirectory for non-C bindings
+   under the module name of =pyme3=.
+
+   In 2016 this PyME module was integrated back into the GPGME project
+   by Justus Winter.  During the course of this work Justus adjusted
+   the port to restore limited support for Python 2, but not as many
+   minor point releases as the original PyME package supports.  During
+   the course of this integration the package was renamed to more
+   accurately reflect its status as a component of GPGME.  The =pyme3=
+   module was renamed to =gpg= and adopted by the upstream GnuPG team.
+
+   In 2017 Justus departed G10code and the GnuPG team.  Following this
+   Ben returned to maintain of gpgme Python bindings and continue
+   building them from that point.
+
+* Relics of the past
+  :PROPERTIES:
+  :CUSTOM_ID: relics-past
+  :END:
+
+There are a few things, in addition to code specific factors, such as
+SWIG itself, which are worth noting here.
+
+** The Annoyances of Git
+   :PROPERTIES:
+   :CUSTOM_ID: the-annoyances-of-git
+   :END:
+
+   As anyone who has ever worked with git knows, submodules are
+   horrible way to deal with pretty much anything.  In the interests
+   of avoiding migraines, that was skipped with addition of the PyME
+   code to GPGME.
+
+   Instead the files were added to a subdirectory of the =lang/=
+   directory, along with a copy of the entire git log up to that point
+   as a separate file within the =lang/python/docs/= directory.[fn:2]
+   As the log for PyME is nearly 100KB and the log for GPGME is
+   approximately 1MB, this would cause considerable bloat, as well as
+   some confusion, should the two be merged.
+
+   Hence the unfortunate, but necessary, step to simply move the
+   files.  A regular repository version has been maintained should it
+   be possible to implement this better in the future.
+
+** The Perils of PyPI
+   :PROPERTIES:
+   :CUSTOM_ID: the-perils-of-pypi
+   :END:
+
+   The early port of the Python 2 =pyme= module as =pyme3= was never
+   added to PyPI while the focus remained on development and testing
+   during 2015 and early 2016.  Later in 2016, however, when Justus
+   completed his major integration work and subsequently renamed the
+   module from =pyme3= to =gpg=, some prior releases were also
+   provided through PyPI.
+
+   Since these bindings require a matching release of the GPGME
+   libraries in order to function, it was determined that there was
+   little benefit in also providing a copy through PyPI since anyone
+   obtaining the GPGME source code would obtain the Python bindings
+   source code at the same time.  Whereas there was the potential to
+   sew confusion amongst Python users installing the module from PyPI,
+   only to discover that without the relevant C files, header files or
+   SWIG compiled binaries, the Python module did them little good.
+
+   There are only two files on PyPI which might turn up in a search
+   for this module or a sample of its content:
+
+   1. gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
+   2. pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
+
+*** GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library
+    :PROPERTIES:
+    :CUSTOM_ID: pypi-gpgme-180
+    :END:
+
+    This is the most recent version to reach PyPI and is the version
+    of the official Pyhon bindings which shipped with GPGME 1.8.0.  If
+    you have GPGME 1.8.0 installed and /only/ 1.8.0 installed, then it
+    is probably safe to use this copy from PyPI.
+
+    As there have been a lot of changes since the release of GPGME
+    1.8.0, the GnuPG Project recommends not using this version of the
+    module and instead installing the current version of GPGME along
+    with the Python bindings included with that package.
+
+*** PyME 0.9.0 - Python support for GPGME GnuPG cryptography library
+    :PROPERTIES:
+    :CUSTOM_ID: pypi-gpgme-90
+    :END:
+
+    This is the last release of the PyME bindings maintained by Martin
+    Albrecht and is only compatible with Python 2, it will not work
+    with Python 3.  This is the version of the software from which the
+    port from Python 2 to Python 3 code was made in 2015.
+
+    Users of the more recent Python bindings will recognise numerous
+    points of similarity, but also significant differences.  It is
+    likely that the more recent official bindings will feel "more
+    pythonic."
+
+    For those using Python 2, there is essentially no harm in using
+    this module, but it may lack a number of more recent features
+    added to GPGME.
+
+* Footnotes
+
+[fn:1] In all likelihood thos would have been Python 2.2 or possibly
+Python 2.3.
+
+[fn:2] The entire PyME git log and other preceding VCS logs are
+located in the =gpgme/lang/python/docs/old-commits.log= file.
diff --git a/lang/python/docs/Short_History.rst b/lang/python/docs/Short_History.rst
deleted file mode 100644
index 8f609272..00000000
--- a/lang/python/docs/Short_History.rst
+++ /dev/null
@@ -1,57 +0,0 @@
-==========================================
-A Short History of gpg bindings for Python
-==========================================
-
-In 2002 John Goerzen released PyME; Python bindings for the GPGME
-module which utilised the current release of Python of the time
-(Python 2.2 or 2.3) and SWIG.  Shortly after creating it and ensuring
-it worked he stopped supporting it, though left his work available on
-his Gopher site.
-
-A couple of years later the project was picked up by Igor Belyi and
-actively developed and maintained by him from 2004 to 2008.  Igor's
-whereabouts at the time of this document's creation are unknown, but
-the current authors do hope he is well.  We're assuming (or hoping)
-that life did what life does and made continuing untenable.
-
-In 2014 Martin Albrecht wanted to patch a bug in the PyME code and
-discovered the absence of Igor.  Following a discussion on the PyME
-mailing list he became the new maintainer for PyME, releasing version
-0.9.0 in May of that year.  He remains the maintainer of the original
-PyME release in Python 2.6 and 2.7 (available via PyPI).
-
-In 2015 Ben McGinnes approached Martin about a Python 3 version, while
-investigating how complex a task this would be the task ended up being
-completed.  A subsequent discussion with Werner Koch led to the
-decision to fold the Python 3 port back into the original GPGME
-release in the languages subdirectory for non-C bindings.  Ben is the
-maintainer of the Python 3 port within GPGME.
-
-In 2016 PyME was renamed to "gpg" and adopted by the upstream GnuPG
-team.
-
----------------------
-The Annoyances of Git
----------------------
-
-As anyone who has ever worked with git knows, submodules are horrible
-way to deal with pretty much anything.  In the interests of avoiding
-migraines, that is being skipped with addition of PyME to GPGME.
-Instead the files will be added to the subdirectory, along with a copy
-of the entire git log up to that point as a separate file within the
-docs directory (old-commits.log).  As the log for PyME is nearly 100KB
-and the log for GPGME is approximately 1MB, this would cause
-considerable bloat, as well as some confusion, should the two be
-merged.  Hence the unfortunate, but necessary, step to simply move the
-files.  A regular repository version will be maintained should it be
-possible to implement this better in the future.
-
-
-------------------
-The Perils of PyPI
-------------------
-
-At the current time the Python 3 fork is not available via PyPI and
-the pip installer.  The recommended installation method is to follow
-the instructions in lang/py3-pyme/INSTALL.  This will build the
-necessary SWIG portions against the installed version of GPGME.
diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org
new file mode 100644
index 00000000..9f039d81
--- /dev/null
+++ b/lang/python/docs/TODO.org
@@ -0,0 +1,144 @@
+#+TITLE: Stuff To Do
+#+LATEX_COMPILER: xelatex
+#+LATEX_CLASS: article
+#+LATEX_CLASS_OPTIONS: [12pt]
+#+LATEX_HEADER: \usepackage{xltxtra}
+#+LATEX_HEADER: \usepackage[margin=1in]{geometry}
+#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Latin Modern Roman}
+
+* Project Task List
+  :PROPERTIES:
+  :CUSTOM_ID: task-list
+  :END:
+
+** DONE Documentation default format
+   CLOSED: [2018-02-15 Thu 21:29]
+   :PROPERTIES:
+   :CUSTOM_ID: todo-docs-default
+   :END:
+
+   Decide on a default file format for documentation.  The two main
+   contenders being Org Mode, the default for the GnuPG Project and
+   reStructuredText, the default for Python projects.  A third option
+   of DITA XML was considered due to a number of beneficial features
+   it provides.
+
+   The decision was made to use Org Mode in order to fully integrate
+   with the rest of the GPGME and GnuPG documentation.  It is possible
+   to produce reST versions via Pandoc and DITA XML can be reached
+   through converting to either Markdown or XHTML first.
+
+** TODO Documentation HOWTO
+   :PROPERTIES:
+   :CUSTOM_ID: todo-docs-howto
+   :END:
+
+   Write a HOWTO style guide for the current Python bindings.
+
+** TODO Documentation SWIG
+   :PROPERTIES:
+   :CUSTOM_ID: todo-docs-swig
+   :END:
+
+   Write documentation for the complete SWIG bindings demonstrating
+   the correspondence with GPGME itself.
+
+   Note: it is likely that this will be more in the nature of
+   something to be used in conjunction with the existing GPGME
+   documentation which makes it easier for Python developers to use.
+
+** TODO GUI examples
+   :PROPERTIES:
+   :CUSTOM_ID: todo-gui-examples
+   :END:
+
+   Create some examples of using Python bindings in a GUI application
+   to either match or be similar to the old GTK2 examples available
+   with PyME.
+
+** TODO Replace SWIG
+   :PROPERTIES:
+   :CUSTOM_ID: todo-replace-swig
+   :END:
+
+   Selecting SWIG for this project in 2002 was understandable and
+   effectively the only viable option.  The options available now,
+   however, are significantly improved and some of those would resolve
+   a number of existing problems with using SWIG, particularly when
+   running code on both POSIX compliant and Windows platforms.
+
+   The long term goal is to replace SWIG by reimplementing the Python
+   bindings using a more suitable means of interfacing with the GPGME
+   C source code.
+
+*** TODO Replacement for SWIG
+    :PROPERTIES:
+    :CUSTOM_ID: todo-replace-swig-replacement
+    :END:
+
+    Decide on a replacement for SWIG.  Currently CFFI is looking like
+    the most viable candidate, but some additional testing and checks
+    are yet to be completed.
+
+** TODO API for an API
+   :PROPERTIES:
+   :CUSTOM_ID: todo-api-squared
+   :END:
+
+   A C API like GPGME is not what most modern developers think of when
+   they hear the term API. Normally they think of something they can
+   interact with like a RESTful web API.  Though RESTful is unlikely
+   given the nature of GPGME and the process of encryption, it may be
+   possible to provide a more familiar interface which can be utilised
+   by developers of other languages for which bindings are not
+   available or for which it is too difficult to create proper
+   bindings.
+
+* Project Task Details
+  :PROPERTIES:
+  :CUSTOM_ID: detailed-tasks
+  :END:
+
+** Working examples
+   :PROPERTIES:
+   :CUSTOM_ID: working-examples
+   :END:
+
+   The old GUI examples were unable to be retained since they depended
+   on GTK2 and Python 2's integration with GTK2.
+
+   Current GPGME examples so far only include command line tools or
+   basic Python code for use with either Python 2.7 or Python 3.4 and
+   above.
+
+   Future GUI examples ought to utilise available GUI modules and
+   libraries supported by Python 3.  This may include Qt frameworks,
+   Tkinter, GTK3 or something else entirely.
+
+** Documentation
+   :PROPERTIES:
+   :CUSTOM_ID: documentation
+   :END:
+
+   The legacy documentation which no longer applies to the Python
+   bindings has been removed.
+
+   Current and future documentation will adhere to the GnuPG standard
+   of using Org Mode and not use the reStructuredText (reST) format
+   more commonly associated with Python documentation.  The reasons
+   for this are that this project is best served as shipping with the
+   rest of GPGME and the documentation ought to match that.  There are
+   also aspects of Org Mode's publishing features which are superior
+   to the defaults of reST, including the capacity to generate fully
+   validating strict XHTML output.
+
+   If reST files are required at a later point for future inclusion
+   with other Python packages, then that format can be generated from
+   the .org files with Pandoc before being leveraged by either
+   Docutils, Sphinx or something else.
+
+   While there are some advanced typesetting features of reST which
+   are not directly available to Org Mode, more often than not those
+   features are best implemented with either HTML and CSS, with LaTeX
+   to produce a PDF or via a number of XML solutions.  Both reST and
+   Org Mode have multiple paths by which to achieve all of these.
diff --git a/lang/python/docs/TODO.rst b/lang/python/docs/TODO.rst
deleted file mode 100644
index a398ccdf..00000000
--- a/lang/python/docs/TODO.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-===========
-Stuff To Do
-===========
-
-----------------
-Working examples
-----------------
-
-The examples from the Python 2 code base do not work and it appears
-that they don't under Python 2 either.  These ought to be replaced or
-updated with examples from the GPGME documentation.
-
-
--------------
-Documentation
--------------
-
-Currently this appears to be buried in the debian/ directory for some
-unknown reason, probably pertaining to one of the other developers.
-Documentation is to be moved to a more appropriate docs/ directory and
-produced using reST in preparation for inevitable publication by way
-of Sphinx and the existing infrastructure at readthedocs.org or the
-projects new home at gnupg.org.