gpgme/lang/python/docs/TODO.org

#+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 Start python bindings HOWTO
    :PROPERTIES:
    :CUSTOM_ID: howto-start
    :END:

** 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.