GpgFrontend/gpgme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: python docs restructure

Browse Source 
* Moved the what's new section out of the HOWTO (mostly), in
  anticipation of expanding the docs to be more than merely a HOWTO.
This commit is contained in:
Ben McGinnes 2018-10-31 03:41:47 +11:00
parent d5c22966d5
commit 78be1e2f54
4 changed files with 168 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
lang/python/doc/src/gpgme-python-howto
View 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

4
lang/python/doc/src/index
View 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]]

43
lang/python/doc/src/what-is-new Normal file
View File

@ -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]].

106
lang/python/doc/src/what-was-new Normal file
View File

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