docs: python docs restructure
authorBen McGinnes <ben@adversary.org>
Tue, 30 Oct 2018 16:41:47 +0000 (03:41 +1100)
committerBen McGinnes <ben@adversary.org>
Tue, 30 Oct 2018 16:41:47 +0000 (03:41 +1100)
* Moved the what's new section out of the HOWTO (mostly), in
  anticipation of expanding the docs to be more than merely a HOWTO.

lang/python/doc/src/gpgme-python-howto
lang/python/doc/src/index
lang/python/doc/src/what-is-new [new file with mode: 0644]
lang/python/doc/src/what-was-new [new file with mode: 0644]

index 1e83e09..ffcb1d4 100644 (file)
@@ -77,78 +77,25 @@ major releases.
    :CUSTOM_ID: new-stuff
    :END:
 
-The most obviously new point for those reading this guide is this
-section on other new things, but that's hardly important.  Not given
-all the other things which spurred the need for adding this section
-and its subsections.
+Full details of what is new are now available in the [[file:what-is-new.org][What's New]] file
+and archives of the preceding /What's New/ sections are available in
+the [[file:what-was-new][What Was New]] file.
+
+
+*** New in GPGME 1·13·0
+    :PROPERTIES:
+    :CUSTOM_ID: new-stuff-1-13-0
+    :END:
+
+See the [[file:what-is-new#new-stuff-1-13-0][What's New]] document for what is new in version 1.13.0.
+
 
 *** New in GPGME 1·12·0
     :PROPERTIES:
     :CUSTOM_ID: new-stuff-1-12-0
     :END:
 
-There have been quite a number of additions to GPGME and the Python
-bindings to it since the last release of GPGME with versions 1.11.0
-and 1.11.1 in April, 2018.
-
-The bullet points of new additiions are:
-
-- an expanded section on [[#installation][installing]] and [[#snafu][troubleshooting]] the Python
-  bindings.
-- The release of Python 3.7.0; which appears to be working just fine
-  with our bindings, in spite of intermittent reports of problems for
-  many other Python projects with that new release.
-- Python 3.7 has been moved to the head of the specified python
-  versions list in the build process.
-- In order to fix some other issues, there are certain underlying
-  functions which are more exposed through the [[#howto-get-context][gpg.Context()]], but
-  ongoing documentation ought to clarify that or otherwise provide the
-  best means of using the bindings.  Some additions to =gpg.core= and
-  the =Context()=, however, were intended (see below).
-- Continuing work in identifying and confirming the cause of
-  oft-reported [[#snafu-runtime-not-funtime][problems installing the Python bindings on Windows]].
-- GSOC: Google's Surreptitiously Ordered Conscription ... erm ... oh,
-  right; Google's Summer of Code.  Though there were two hopeful
-  candidates this year; only one ended up involved with the GnuPG
-  Project directly, the other concentrated on an unrelated third party
-  project with closer ties to one of the GNU/Linux distributions than
-  to the GnuPG Project.  Thus the Python bindings benefited from GSOC
-  participant Jacob Adams, who added the key_import function; building
-  on prior work by Tobias Mueller.
-- Several new methods functions were added to the gpg.Context(),
-  including: [[#howto-import-key][key_import]], [[#howto-export-key][key_export]], [[#howto-export-public-key][key_export_minimal]] and
-  [[#howto-export-secret-key][key_export_secret]].
-- Importing and exporting examples include versions integrated with
-  Marcel Fest's recently released [[https://github.com/Selfnet/hkp4py][HKP for Python]] module.  Some
-  [[#hkp4py][additional notes on this module]] are included at the end of the HOWTO.
-- Instructions for dealing with semi-walled garden implementations
-  like ProtonMail are also included.  This is intended to make things
-  a little easier when communicating with users of ProtonMail's
-  services and should not be construed as an endorsement of said
-  service.  The GnuPG Project neither favours, nor disfavours
-  ProtonMail and the majority of this deals with interacting with the
-  ProtonMail keyserver.
-- Semi-formalised the location where [[#draft-editions][draft versions]] of this HOWTO may
-  periodically be accessible.  This is both for the reference of
-  others and testing the publishing of the document itself.  Renamed
-  this file at around the same time.
-- The Texinfo documentation build configuration has been replicated
-  from the parent project in order to make to maintain consistency
-  with that project (and actually ship with each release).
-- a reStructuredText (=.rst=) version is also generated for Python
-  developers more used to and comfortable with that format as it is
-  the standard Python documentation format and Python developers may
-  wish to use it with Sphinx.  Please note that there has been no
-  testing of the reStructuredText version with Sphinx at all.  The
-  reST file was generated by the simple expedient of using [[https://pandoc.org/][Pandoc]].
-- Added a new section for [[#advanced-use][advanced or experimental use]].
-- Began the advanced use cases with [[#cython][a section]] on using the module with
-  [[https://cython.org/][Cython]].
-- Added a number of new scripts to the =example/howto/= directory;
-  some of which may be in advance of their planned sections of the
-  HOWTO (and some are just there because it seemed like a good idea at
-  the time).
-- Cleaned up a lot of things under the hood.
+See the [[file:what-was-new#new-stuff-1-12-0][What Was New]] document for what was new in version 1.12.0.
 
 
 * GPGME Concepts
@@ -2983,15 +2930,16 @@ from the author at any of the following URLs:
 
 All of these draft versions except for one have been generated from
 this document via Emacs [[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]].  Though it is likely
-that the specific [[https://files.au.adversary.org/crypto/gpgme-python-howto.org][file]] [[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server with
+that the specific [[https://files.au.adversary.org/crypto/gpgme-python-howto][file]] [[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server with
 the generated output formats.
 
 The one exception is the reStructuredText version, which was converted
 using the latest version of Pandoc from the Org mode source file using
-the following command:
+either of the following two commands:
 
 #+BEGIN_SRC shell
   pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto.org
+  pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto
 #+END_SRC
 
 In addition to these there is a significantly less frequently updated
@@ -3025,7 +2973,7 @@ PURPOSE.
 
 * Footnotes
 
-[fn:1] =short-history.org= and/or =short-history.html=.
+[fn:1] =short-history= and/or =short-history.html=.
 
 [fn:2] With no issues reported specific to Python 3.7, the release of
 Python 3.7.1 at around the same time as GPGME 1.12.0 and the testing
index 9fe7a3c..18c9386 100644 (file)
@@ -22,5 +22,5 @@
    :END:
 
 
-- [[file:short-history.org][A short history of the project]]
-- [[file:gpgme-python-howto.org][GPGME Python Bindings HOWTO]]
+- [[file:short-history][A short history of the project]]
+- [[file:gpgme-python-howto][GPGME Python Bindings HOWTO]]
diff --git a/lang/python/doc/src/what-is-new b/lang/python/doc/src/what-is-new
new file mode 100644 (file)
index 0000000..4ca8ea8
--- /dev/null
@@ -0,0 +1,43 @@
+# -*- mode: org -*-
+#+TITLE: What's New in the GPGME Python Bindings and Documentation
+#+AUTHOR: Ben McGinnes
+#+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}]{Times New Roman}
+#+LATEX_HEADER: \author{Ben McGinnes <ben@gnupg.org>}
+
+
+* What's New
+  :PROPERTIES:
+  :CUSTOM_ID: new-stuff
+  :END:
+
+| Version:        | 0.0.1-draft                              |
+| GPGME Version:  | 1.13.0                                   |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <ben@gnupg.org>             |
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
+| Language:       | Australian English, British English      |
+| xml:lang:       | en-AU, en-GB, en                         |
+
+Last time the most obviously new thing was adding the /What's New/
+section to the HOWTO.  Now it's moving it out of the HOWTO.  Not to
+mention expanding on the documentation both generally and
+considerably.
+
+
+** New in GPGME 1·13·0
+   :PROPERTIES:
+   :CUSTOM_ID: new-stuff-1-13-0
+   :END:
+
+Additions since GPGME 1.12.0 include:
+
+- An advanced HOWTO on using the bindings with web interfaces,
+  specifically Flask.
+- Moving the /What's New/ section out of the basic [[file:gpgme-python-howto.org][HOWTO]] document and
+  into its own file so as to more readily include other documents
+  beyond that HOWTO.
+- Moving the preceding, archival, segments into [[file:what-was-new.org][another file]].
diff --git a/lang/python/doc/src/what-was-new b/lang/python/doc/src/what-was-new
new file mode 100644 (file)
index 0000000..666e5cc
--- /dev/null
@@ -0,0 +1,106 @@
+# -*- mode: org -*-
+#+TITLE: What Was New in the GPGME Python Bindings and Documentation
+#+AUTHOR: Ben McGinnes
+#+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}]{Times New Roman}
+#+LATEX_HEADER: \author{Ben McGinnes <ben@gnupg.org>}
+
+
+* What Was New
+  :PROPERTIES:
+  :CUSTOM_ID: new-stuff
+  :END:
+
+| Version:        | 0.0.1-draft                              |
+| GPGME Version:  | 1.13.0                                   |
+| Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <ben@gnupg.org>             |
+| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
+| Language:       | Australian English, British English      |
+| xml:lang:       | en-AU, en-GB, en                         |
+
+The following are all the past /What's New/ sections for the Python
+Bindings HOWTO and other documentation.
+
+
+** What Was New in GPGME 1·12·0
+   :PROPERTIES:
+   :CUSTOM_ID: gpgme-1-12-0
+   :END:
+
+The most obviously new point for those reading this guide is this
+section on other new things, but that’s hardly important. Not given
+all the other things which spurred the need for adding this section
+and its subsections.
+
+
+*** New in GPGME 1·12·0
+    :PROPERTIES:
+    :CUSTOM_ID: new-stuff-1-12-0
+    :END:
+
+There have been quite a number of additions to GPGME and the Python
+bindings to it since the last release of GPGME with versions 1.11.0
+and 1.11.1 in April, 2018.
+
+The bullet points of new additiions are:
+
+- an expanded section on [[#installation][installing]] and [[#snafu][troubleshooting]] the Python
+  bindings.
+- The release of Python 3.7.0; which appears to be working just fine
+  with our bindings, in spite of intermittent reports of problems for
+  many other Python projects with that new release.
+- Python 3.7 has been moved to the head of the specified python
+  versions list in the build process.
+- In order to fix some other issues, there are certain underlying
+  functions which are more exposed through the [[#howto-get-context][gpg.Context()]], but
+  ongoing documentation ought to clarify that or otherwise provide the
+  best means of using the bindings.  Some additions to =gpg.core= and
+  the =Context()=, however, were intended (see below).
+- Continuing work in identifying and confirming the cause of
+  oft-reported [[#snafu-runtime-not-funtime][problems installing the Python bindings on Windows]].
+- GSOC: Google's Surreptitiously Ordered Conscription ... erm ... oh,
+  right; Google's Summer of Code.  Though there were two hopeful
+  candidates this year; only one ended up involved with the GnuPG
+  Project directly, the other concentrated on an unrelated third party
+  project with closer ties to one of the GNU/Linux distributions than
+  to the GnuPG Project.  Thus the Python bindings benefited from GSOC
+  participant Jacob Adams, who added the key_import function; building
+  on prior work by Tobias Mueller.
+- Several new methods functions were added to the gpg.Context(),
+  including: [[#howto-import-key][key_import]], [[#howto-export-key][key_export]], [[#howto-export-public-key][key_export_minimal]] and
+  [[#howto-export-secret-key][key_export_secret]].
+- Importing and exporting examples include versions integrated with
+  Marcel Fest's recently released [[https://github.com/Selfnet/hkp4py][HKP for Python]] module.  Some
+  [[#hkp4py][additional notes on this module]] are included at the end of the HOWTO.
+- Instructions for dealing with semi-walled garden implementations
+  like ProtonMail are also included.  This is intended to make things
+  a little easier when communicating with users of ProtonMail's
+  services and should not be construed as an endorsement of said
+  service.  The GnuPG Project neither favours, nor disfavours
+  ProtonMail and the majority of this deals with interacting with the
+  ProtonMail keyserver.
+- Semi-formalised the location where [[#draft-editions][draft versions]] of this HOWTO may
+  periodically be accessible.  This is both for the reference of
+  others and testing the publishing of the document itself.  Renamed
+  this file at around the same time.
+- The Texinfo documentation build configuration has been replicated
+  from the parent project in order to make to maintain consistency
+  with that project (and actually ship with each release).
+- a reStructuredText (=.rst=) version is also generated for Python
+  developers more used to and comfortable with that format as it is
+  the standard Python documentation format and Python developers may
+  wish to use it with Sphinx.  Please note that there has been no
+  testing of the reStructuredText version with Sphinx at all.  The
+  reST file was generated by the simple expedient of using [[https://pandoc.org/][Pandoc]].
+- Added a new section for [[#advanced-use][advanced or experimental use]].
+- Began the advanced use cases with [[#cython][a section]] on using the module with
+  [[https://cython.org/][Cython]].
+- Added a number of new scripts to the =example/howto/= directory;
+  some of which may be in advance of their planned sections of the
+  HOWTO (and some are just there because it seemed like a good idea at
+  the time).
+- Cleaned up a lot of things under the hood.