From c4fa4216199b16c1f169725c0a1e0a40764b1ebb Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Wed, 14 Feb 2018 21:24:54 +1100 Subject: TODO * Converted document from reST to org-mode. --- lang/python/docs/TODO.org | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 lang/python/docs/TODO.org (limited to 'lang/python/docs/TODO.org') diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org new file mode 100644 index 00000000..8930b800 --- /dev/null +++ b/lang/python/docs/TODO.org @@ -0,0 +1,22 @@ +#+TITLE: Stuff To Do + +* Working examples + :PROPERTIES: + :CUSTOM_ID: working-examples + :END: + +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 + :PROPERTIES: + :CUSTOM_ID: documentation + :END: + +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. -- cgit v1.2.3 From fccd2ea3871f5d63fb038db0733a34f9c5d550c3 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Wed, 14 Feb 2018 22:28:50 +1100 Subject: TODO * Updated TODO. * The entirety of the old TODO has been replaced with either more relevant tasks or goals for the examples and a more measured approach to the docs and why, in this project, Org Mode trumps reST, even though it's Python through and through. --- lang/python/docs/TODO.org | 65 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 45 insertions(+), 20 deletions(-) (limited to 'lang/python/docs/TODO.org') diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index 8930b800..74b478dc 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -1,22 +1,47 @@ #+TITLE: Stuff To Do -* Working examples - :PROPERTIES: - :CUSTOM_ID: working-examples - :END: - -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 - :PROPERTIES: - :CUSTOM_ID: documentation - :END: - -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. +* TODO + +** 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 reST 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. Furthermore, there are 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. -- cgit v1.2.3 From 40da5022922172ed898172956a8ccf5622e5638d Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Thu, 15 Feb 2018 21:28:07 +1100 Subject: TODO * Beginning to turn the first part of this into something kind of like an actual TODO list as Org Mode uses it (maybe). --- lang/python/docs/TODO.org | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) (limited to 'lang/python/docs/TODO.org') diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index 74b478dc..c0ec5562 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -1,6 +1,33 @@ #+TITLE: Stuff To Do -* TODO +* Project Task List + +** TODO Documentation default format + :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 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. + +* Project Task Details ** Working examples :PROPERTIES: @@ -27,12 +54,12 @@ bindings has been removed. Current and future documentation will adhere to the GnuPG standard - of using Org Mode and not use the reST 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. Furthermore, there are aspects - of Org Mode's publishing features which are superior to the - defaults of reST, including the capacity to generate fully + 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 -- cgit v1.2.3 From 235d899a5fc24cdf9c856adbc021a69c43985c99 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Thu, 15 Feb 2018 21:30:32 +1100 Subject: TODO Documentation * Checked off the decision to stick with Org Mode. --- lang/python/docs/TODO.org | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'lang/python/docs/TODO.org') diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index c0ec5562..1ddd394e 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -2,7 +2,8 @@ * Project Task List -** TODO Documentation default format +** DONE Documentation default format + CLOSED: [2018-02-15 Thu 21:29] :PROPERTIES: :CUSTOM_ID: todo-docs-default :END: -- cgit v1.2.3 From 6f15d821404742ac2683f54ca4102ee4aaedacf2 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Fri, 16 Feb 2018 01:26:20 +1100 Subject: LaTeX margins * Added LaTeX header for 1 inch margins in the quite likely event that all PDF output ultimately uses LaTeX. --- lang/python/docs/TODO.org | 65 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) (limited to 'lang/python/docs/TODO.org') diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index 1ddd394e..10324e60 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -1,6 +1,11 @@ #+TITLE: Stuff To Do +#+LATEX_CLASS: article +#+LATEX_HEADER: \usepackage[margin=1in]{geometry} * Project Task List + :PROPERTIES: + :CUSTOM_ID: task-list + :END: ** DONE Documentation default format CLOSED: [2018-02-15 Thu 21:29] @@ -19,6 +24,25 @@ 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 @@ -28,7 +52,48 @@ 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: -- cgit v1.2.3 From 6f2e2e0f150d5c6d53de5bc48af137f7864d5fd9 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Mon, 26 Feb 2018 13:51:23 +1100 Subject: LaTeX headers * Set LaTeX headers to enable ligatures and a 12pt font by default. * Paper size left for regional defaults. * Using XeLaTeX for easier font control. * Using default LaTeX font of Latin Main, but that's easy enough to change. --- lang/python/docs/TODO.org | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'lang/python/docs/TODO.org') diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index 10324e60..9f039d81 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -1,6 +1,10 @@ #+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: -- cgit v1.2.3