doc: python bindings 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 ** STARTED Documentation HOWTO
32    :PROPERTIES:
33    :CUSTOM_ID: todo-docs-howto
34    :END:
35
36    - State "STARTED"    from "TODO"       [2018-03-08 Thu 13:59] \\
37      Started yesterday.
38    Write a HOWTO style guide for the current Python bindings.
39
40 *** DONE Start python bindings HOWTO
41     CLOSED: [2018-03-07 Wed 18:14]
42     :PROPERTIES:
43     :CUSTOM_ID: howto-start
44     :END:
45
46 *** STARTED Include certain specific instructions in the HOWTO
47     :PROPERTIES:
48     :CUSTOM_ID: howto-requests
49     :END:
50
51     - State "STARTED"    from "TODO"       [2018-03-09 Fri 15:27]
52     Some functions can be worked out from the handful of examples
53     available, but many more can't and I've already begun receiving
54     requests for certain functions to be explained.
55
56 **** STARTED Standard scenarios
57      :PROPERTIES:
58      :CUSTOM_ID: howto-the-basics
59      :END:
60
61      - State "STARTED"    from "TODO"       [2018-03-09 Fri 15:26] \\
62        Began with the example code, now to add the text.
63      What everyone expects: encryption, decryption, signing and verifying.
64
65 **** TODO Key control
66      :PROPERTIES:
67      :CUSTOM_ID: howto-key-control
68      :END:
69
70      Generating keys, adding subkeys, revoking subkeys (and keeping
71      the cert key), adding and revoking UIDs, signing/certifying keys.
72
73 **** TODO More key control
74      :PROPERTIES:
75      :CUSTOM_ID: howto-key-selection
76      :END:
77
78      Selecting keys to encrypt to or manipulate in other ways (e.g. as
79      with key control or the basics).
80
81 **** TODO S/MIME
82      :PROPERTIES:
83      :CUSTOM_ID: howto-s-mime
84      :END:
85
86      Eventually add some of this, but it the OpenPGP details are far
87      more important at the moment.
88
89 ** TODO Documentation SWIG
90    :PROPERTIES:
91    :CUSTOM_ID: todo-docs-swig
92    :END:
93
94    Write documentation for the complete SWIG bindings demonstrating
95    the correspondence with GPGME itself.
96
97    Note: it is likely that this will be more in the nature of
98    something to be used in conjunction with the existing GPGME
99    documentation which makes it easier for Python developers to use.
100
101 ** TODO GUI examples
102    :PROPERTIES:
103    :CUSTOM_ID: todo-gui-examples
104    :END:
105
106    Create some examples of using Python bindings in a GUI application
107    to either match or be similar to the old GTK2 examples available
108    with PyME.
109
110 ** TODO Replace SWIG
111    :PROPERTIES:
112    :CUSTOM_ID: todo-replace-swig
113    :END:
114
115    Selecting SWIG for this project in 2002 was understandable and
116    effectively the only viable option.  The options available now,
117    however, are significantly improved and some of those would resolve
118    a number of existing problems with using SWIG, particularly when
119    running code on both POSIX compliant and Windows platforms.
120
121    The long term goal is to replace SWIG by reimplementing the Python
122    bindings using a more suitable means of interfacing with the GPGME
123    C source code.
124
125 *** TODO Replacement for SWIG
126     :PROPERTIES:
127     :CUSTOM_ID: todo-replace-swig-replacement
128     :END:
129
130     Decide on a replacement for SWIG.  Currently CFFI is looking like
131     the most viable candidate, but some additional testing and checks
132     are yet to be completed.
133
134 ** TODO API for an API
135    :PROPERTIES:
136    :CUSTOM_ID: todo-api-squared
137    :END:
138
139    A C API like GPGME is not what most modern developers think of when
140    they hear the term API. Normally they think of something they can
141    interact with like a RESTful web API.  Though RESTful is unlikely
142    given the nature of GPGME and the process of encryption, it may be
143    possible to provide a more familiar interface which can be utilised
144    by developers of other languages for which bindings are not
145    available or for which it is too difficult to create proper
146    bindings.
147
148
149 * Project Task Details
150   :PROPERTIES:
151   :CUSTOM_ID: detailed-tasks
152   :END:
153
154 ** Working examples
155    :PROPERTIES:
156    :CUSTOM_ID: working-examples
157    :END:
158
159    The old GUI examples were unable to be retained since they depended
160    on GTK2 and Python 2's integration with GTK2.
161
162    Current GPGME examples so far only include command line tools or
163    basic Python code for use with either Python 2.7 or Python 3.4 and
164    above.
165
166    Future GUI examples ought to utilise available GUI modules and
167    libraries supported by Python 3.  This may include Qt frameworks,
168    Tkinter, GTK3 or something else entirely.
169
170 ** Documentation
171    :PROPERTIES:
172    :CUSTOM_ID: documentation
173    :END:
174
175    The legacy documentation which no longer applies to the Python
176    bindings has been removed.
177
178    Current and future documentation will adhere to the GnuPG standard
179    of using Org Mode and not use the reStructuredText (reST) format
180    more commonly associated with Python documentation.  The reasons
181    for this are that this project is best served as shipping with the
182    rest of GPGME and the documentation ought to match that.  There are
183    also aspects of Org Mode's publishing features which are superior
184    to the defaults of reST, including the capacity to generate fully
185    validating strict XHTML output.
186
187    If reST files are required at a later point for future inclusion
188    with other Python packages, then that format can be generated from
189    the .org files with Pandoc before being leveraged by either
190    Docutils, Sphinx or something else.
191
192    While there are some advanced typesetting features of reST which
193    are not directly available to Org Mode, more often than not those
194    features are best implemented with either HTML and CSS, with LaTeX
195    to produce a PDF or via a number of XML solutions.  Both reST and
196    Org Mode have multiple paths by which to achieve all of these.