Merge branch 'ben/python-docs-01'

* Documentation and the first brush strokes towards the future.

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

1 files changed, 144 insertions, 0 deletions

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.