TODO - HOWTO
[gpgme.git] / lang / python / docs / TODO.org
1 #+TITLE: Stuff To Do
2 #+LATEX_COMPILER: xelatex
3 #+LATEX_CLASS: article
4 #+LATEX_CLASS_OPTIONS: [12pt]
5 #+LATEX_HEADER: \usepackage{xltxtra}
6 #+LATEX_HEADER: \usepackage[margin=1in]{geometry}
7 #+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Latin Modern Roman}
8
9 * Project Task List
10   :PROPERTIES:
11   :CUSTOM_ID: task-list
12   :END:
13
14 ** DONE Documentation default format
15    CLOSED: [2018-02-15 Thu 21:29]
16    :PROPERTIES:
17    :CUSTOM_ID: todo-docs-default
18    :END:
19
20    Decide on a default file format for documentation.  The two main
21    contenders being Org Mode, the default for the GnuPG Project and
22    reStructuredText, the default for Python projects.  A third option
23    of DITA XML was considered due to a number of beneficial features
24    it provides.
25
26    The decision was made to use Org Mode in order to fully integrate
27    with the rest of the GPGME and GnuPG documentation.  It is possible
28    to produce reST versions via Pandoc and DITA XML can be reached
29    through converting to either Markdown or XHTML first.
30
31 ** TODO Documentation HOWTO
32    :PROPERTIES:
33    :CUSTOM_ID: todo-docs-howto
34    :END:
35
36    Write a HOWTO style guide for the current Python bindings.
37
38 *** DONE Start python bindings HOWTO
39     CLOSED: [2018-03-07 Wed 18:14]
40     :PROPERTIES:
41     :CUSTOM_ID: howto-start
42     :END:
43
44 ** TODO Documentation SWIG
45    :PROPERTIES:
46    :CUSTOM_ID: todo-docs-swig
47    :END:
48
49    Write documentation for the complete SWIG bindings demonstrating
50    the correspondence with GPGME itself.
51
52    Note: it is likely that this will be more in the nature of
53    something to be used in conjunction with the existing GPGME
54    documentation which makes it easier for Python developers to use.
55
56 ** TODO GUI examples
57    :PROPERTIES:
58    :CUSTOM_ID: todo-gui-examples
59    :END:
60
61    Create some examples of using Python bindings in a GUI application
62    to either match or be similar to the old GTK2 examples available
63    with PyME.
64
65 ** TODO Replace SWIG
66    :PROPERTIES:
67    :CUSTOM_ID: todo-replace-swig
68    :END:
69
70    Selecting SWIG for this project in 2002 was understandable and
71    effectively the only viable option.  The options available now,
72    however, are significantly improved and some of those would resolve
73    a number of existing problems with using SWIG, particularly when
74    running code on both POSIX compliant and Windows platforms.
75
76    The long term goal is to replace SWIG by reimplementing the Python
77    bindings using a more suitable means of interfacing with the GPGME
78    C source code.
79
80 *** TODO Replacement for SWIG
81     :PROPERTIES:
82     :CUSTOM_ID: todo-replace-swig-replacement
83     :END:
84
85     Decide on a replacement for SWIG.  Currently CFFI is looking like
86     the most viable candidate, but some additional testing and checks
87     are yet to be completed.
88
89 ** TODO API for an API
90    :PROPERTIES:
91    :CUSTOM_ID: todo-api-squared
92    :END:
93
94    A C API like GPGME is not what most modern developers think of when
95    they hear the term API. Normally they think of something they can
96    interact with like a RESTful web API.  Though RESTful is unlikely
97    given the nature of GPGME and the process of encryption, it may be
98    possible to provide a more familiar interface which can be utilised
99    by developers of other languages for which bindings are not
100    available or for which it is too difficult to create proper
101    bindings.
102
103
104 * Project Task Details
105   :PROPERTIES:
106   :CUSTOM_ID: detailed-tasks
107   :END:
108
109 ** Working examples
110    :PROPERTIES:
111    :CUSTOM_ID: working-examples
112    :END:
113
114    The old GUI examples were unable to be retained since they depended
115    on GTK2 and Python 2's integration with GTK2.
116
117    Current GPGME examples so far only include command line tools or
118    basic Python code for use with either Python 2.7 or Python 3.4 and
119    above.
120
121    Future GUI examples ought to utilise available GUI modules and
122    libraries supported by Python 3.  This may include Qt frameworks,
123    Tkinter, GTK3 or something else entirely.
124
125 ** Documentation
126    :PROPERTIES:
127    :CUSTOM_ID: documentation
128    :END:
129
130    The legacy documentation which no longer applies to the Python
131    bindings has been removed.
132
133    Current and future documentation will adhere to the GnuPG standard
134    of using Org Mode and not use the reStructuredText (reST) format
135    more commonly associated with Python documentation.  The reasons
136    for this are that this project is best served as shipping with the
137    rest of GPGME and the documentation ought to match that.  There are
138    also aspects of Org Mode's publishing features which are superior
139    to the defaults of reST, including the capacity to generate fully
140    validating strict XHTML output.
141
142    If reST files are required at a later point for future inclusion
143    with other Python packages, then that format can be generated from
144    the .org files with Pandoc before being leveraged by either
145    Docutils, Sphinx or something else.
146
147    While there are some advanced typesetting features of reST which
148    are not directly available to Org Mode, more often than not those
149    features are best implemented with either HTML and CSS, with LaTeX
150    to produce a PDF or via a number of XML solutions.  Both reST and
151    Org Mode have multiple paths by which to achieve all of these.