python: docs updates
* Multiple updates, expanding on the Windows installation issues. * Also adding to the new maintenance mode reference document. * Includes content relating to the resolution of T4271 and T4191. Tested-by: Ben McGinnes <ben@adversary.org> Signed-off-by: Ben McGinnes <ben@adversary.org>
This commit is contained in:
Ben McGinnes
parent
78f6291a3b
commit
7c63bfe4ab
@ -2048,6 +2048,10 @@ content as a byte object, the recipient key IDs and algorithms in
|
||||
``result`` and the results of verifying any signatures of the data in
|
||||
``verify_result``.
|
||||
|
||||
If ``gpg.Context().decrypt(cfile, verify=False)`` is called instead,
|
||||
then ``verify_result`` will be returned as ``None`` and the rest remains
|
||||
as described here.
|
||||
|
||||
.. _howto-basic-signing:
|
||||
|
||||
Signing text and files
|
||||
@ -3099,11 +3103,11 @@ the author at any of the following URLs:
|
||||
- `GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3
|
||||
SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
|
||||
- `GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no
|
||||
SS) <http://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
|
||||
SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
|
||||
- `GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3
|
||||
SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html>`__
|
||||
- `GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no
|
||||
SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html>`__
|
||||
SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto/index.html>`__
|
||||
|
||||
All of these draft versions except for one have been generated from this
|
||||
document via GNU Emacs `Org mode <https://orgmode.org/>`__ and `GNU
|
||||
@ -3135,12 +3139,24 @@ either of the following commands:
|
||||
|
||||
In addition to these there is a significantly less frequently updated
|
||||
version as a HTML `WebHelp
|
||||
site <https://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html>`__
|
||||
site <https://files.au.adversary.org/crypto/gpgme-python/dita/webhelp/index.html>`__
|
||||
(AWS S3 SSL); generated from DITA XML source files, which can be found
|
||||
in `an alternative
|
||||
branch <https://dev.gnupg.org/source/gpgme/browse/ben%252Fhowto-dita/>`__
|
||||
of the GPGME git repository.
|
||||
|
||||
Various generated output formats may occasionally be found in
|
||||
subdirectories of the
|
||||
`gpgme-python <https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python>`__
|
||||
directory. In particular within the
|
||||
`DITA <https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/dita>`__,
|
||||
`reStructuredText <https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/rst>`__
|
||||
and
|
||||
`Texinfo <https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/texinfo>`__
|
||||
subdirectories. The ``rst`` directory contains output files generated
|
||||
with Sphix and may include a considerable number of its possible output
|
||||
formats.
|
||||
|
||||
These draft editions are not official documents and the version of
|
||||
documentation in the master branch or which ships with released versions
|
||||
is the only official documentation. Nevertheless, these draft editions
|
||||
|
||||
@ -88,3 +88,46 @@ Those with a commercial interest in expediting such a feature request
|
||||
already know how to `expedite
|
||||
it <https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset>`__ (use the
|
||||
message field to state what feature is being requested).
|
||||
|
||||
.. _docs:
|
||||
|
||||
Documentation formats
|
||||
---------------------
|
||||
|
||||
The documentation has been written in Org mode for GNU Emacs, with both
|
||||
Texinfo and reStructuredText formats generated from that. The Texinfo
|
||||
files are intended for use with the rest of the GnuPG documentation;
|
||||
while the reStructuredText files are intended for use with Docutils and
|
||||
Sphinx, as with other Python projects.
|
||||
|
||||
.. _sphinx-made-epubs-suck:
|
||||
|
||||
Cautionary Notes regarding Sphinx and EPUB
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Though Python\'s Docutils in conjunction with Sphinx is capable of
|
||||
generating some very useful HTML sites, as proven by `Read the
|
||||
Docs <https://readthedocs.org/>`__ and the `Python
|
||||
documentation <https://docs.python.org/>`__, there are a number of
|
||||
output formats it does not handle well. At the top of the list of things
|
||||
it manages to break so atrociously as to be embarassing is the `EPUB
|
||||
3 <http://idpf.org/epub>`__ format.
|
||||
|
||||
The automatically generated EPUB of the CPython documentation always
|
||||
contains hundreds of validation errors and even the modest amount of
|
||||
documentation here `produced a
|
||||
file <https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub>`__
|
||||
with approximately thirty validation errors. As the volume of
|
||||
documentation content increases, so does the induced errors. Whereas
|
||||
Texinfo doesn\'t produce EPUB output at all, nor does Org-mode.
|
||||
|
||||
Should there ever be genuine demand for this format, lodge a `feature
|
||||
request <https://dev.gnupg.org/maniphest/task/edit/form/4/>`__ case
|
||||
marked for `my <https://dev.gnupg.org/p/BenM/>`__ attention. The means
|
||||
of generating such files flawlessly is already available, but is not yet
|
||||
part of the GnuPG build system. Nor is it integrated with a means of
|
||||
converting Org mode input files to the relevant base format
|
||||
automatically, as can already be done when converting Org to
|
||||
reStructuredText or Org to Texinfo. As a certain amount of work would be
|
||||
required to get it done, there would need to be clear demand for that
|
||||
work to be done.
|
||||
|
||||
@ -2095,6 +2095,10 @@ content as a byte object, the recipient key IDs and algorithms in
|
||||
=result= and the results of verifying any signatures of the data in
|
||||
=verify_result=.
|
||||
|
||||
If =gpg.Context().decrypt(cfile, verify=False)= is called instead,
|
||||
then =verify_result= will be returned as =None= and the rest remains
|
||||
as described here.
|
||||
|
||||
|
||||
** Signing text and files
|
||||
:PROPERTIES:
|
||||
@ -3163,9 +3167,9 @@ Draft editions of this HOWTO may be periodically available directly
|
||||
from the author at any of the following URLs:
|
||||
|
||||
- [[https://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL)]]
|
||||
- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SS)]]
|
||||
- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SSL)]]
|
||||
- [[https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 SSL)]]
|
||||
- [[http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)]]
|
||||
- [[http://files.au.adversary.org/crypto/gpgme-python-howto/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)]]
|
||||
|
||||
All of these draft versions except for one have been generated from
|
||||
this document via GNU Emacs [[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]]. Though it is
|
||||
@ -3194,10 +3198,16 @@ commands:
|
||||
#+END_SRC
|
||||
|
||||
In addition to these there is a significantly less frequently updated
|
||||
version as a HTML [[https://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html][WebHelp site]] (AWS S3 SSL); generated from DITA XML
|
||||
version as a HTML [[https://files.au.adversary.org/crypto/gpgme-python/dita/webhelp/index.html][WebHelp site]] (AWS S3 SSL); generated from DITA XML
|
||||
source files, which can be found in [[https://dev.gnupg.org/source/gpgme/browse/ben%252Fhowto-dita/][an alternative branch]] of the GPGME
|
||||
git repository.
|
||||
|
||||
Various generated output formats may occasionally be found in
|
||||
subdirectories of the [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python][gpgme-python]] directory. In particular within
|
||||
the [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/dita][DITA]], [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/rst][reStructuredText]] and [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/texinfo][Texinfo]] subdirectories. The =rst=
|
||||
directory contains output files generated with Sphix and may include a
|
||||
considerable number of its possible output formats.
|
||||
|
||||
These draft editions are not official documents and the version of
|
||||
documentation in the master branch or which ships with released
|
||||
versions is the only official documentation. Nevertheless, these
|
||||
|
||||
@ -93,3 +93,43 @@ basis. Expediting such a request would require funding that request.
|
||||
Those with a commercial interest in expediting such a feature request
|
||||
already know how to [[https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset][expedite it]] (use the message field to state what
|
||||
feature is being requested).
|
||||
|
||||
|
||||
** Documentation formats
|
||||
:PROPERTIES:
|
||||
:CUSTOM_ID: docs
|
||||
:END:
|
||||
|
||||
The documentation has been written in Org mode for GNU Emacs, with
|
||||
both Texinfo and reStructuredText formats generated from that. The
|
||||
Texinfo files are intended for use with the rest of the GnuPG
|
||||
documentation; while the reStructuredText files are intended for use
|
||||
with Docutils and Sphinx, as with other Python projects.
|
||||
|
||||
|
||||
*** Cautionary Notes regarding Sphinx and EPUB
|
||||
:PROPERTIES:
|
||||
:CUSTOM_ID: sphinx-made-epubs-suck
|
||||
:END:
|
||||
|
||||
Though Python's Docutils in conjunction with Sphinx is capable of
|
||||
generating some very useful HTML sites, as proven by [[https://readthedocs.org/][Read the Docs]] and
|
||||
the [[https://docs.python.org/][Python documentation]], there are a number of output formats it does
|
||||
not handle well. At the top of the list of things it manages to break
|
||||
so atrociously as to be embarassing is the [[http://idpf.org/epub][EPUB 3]] format.
|
||||
|
||||
The automatically generated EPUB of the CPython documentation always
|
||||
contains hundreds of validation errors and even the modest amount of
|
||||
documentation here [[https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub][produced a file]] with approximately thirty
|
||||
validation errors. As the volume of documentation content increases,
|
||||
so does the induced errors. Whereas Texinfo doesn't produce EPUB
|
||||
output at all, nor does Org-mode.
|
||||
|
||||
Should there ever be genuine demand for this format, lodge a [[https://dev.gnupg.org/maniphest/task/edit/form/4/][feature
|
||||
request]] case marked for [[https://dev.gnupg.org/p/BenM/][my]] attention. The means of generating such
|
||||
files flawlessly is already available, but is not yet part of the
|
||||
GnuPG build system. Nor is it integrated with a means of converting
|
||||
Org mode input files to the relevant base format automatically, as can
|
||||
already be done when converting Org to reStructuredText or Org to
|
||||
Texinfo. As a certain amount of work would be required to get it
|
||||
done, there would need to be clear demand for that work to be done.
|
||||
|
||||
@ -2255,6 +2255,10 @@ content as a byte object, the recipient key IDs and algorithms in
|
||||
@samp{result} and the results of verifying any signatures of the data in
|
||||
@samp{verify_result}.
|
||||
|
||||
If @samp{gpg.Context().decrypt(cfile, verify=False)} is called instead,
|
||||
then @samp{verify_result} will be returned as @samp{None} and the rest remains
|
||||
as described here.
|
||||
|
||||
@node Signing text and files
|
||||
@section Signing text and files
|
||||
|
||||
@ -3301,11 +3305,11 @@ from the author at any of the following URLs:
|
||||
@item
|
||||
@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL)}
|
||||
@item
|
||||
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SS)}
|
||||
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SSL)}
|
||||
@item
|
||||
@uref{https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html, GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 SSL)}
|
||||
@item
|
||||
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html, GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)}
|
||||
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto/index.html, GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)}
|
||||
@end itemize
|
||||
|
||||
All of these draft versions except for one have been generated from
|
||||
@ -3335,10 +3339,16 @@ pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto
|
||||
@end example
|
||||
|
||||
In addition to these there is a significantly less frequently updated
|
||||
version as a HTML @uref{https://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html, WebHelp site} (AWS S3 SSL); generated from DITA XML
|
||||
version as a HTML @uref{https://files.au.adversary.org/crypto/gpgme-python/dita/webhelp/index.html, WebHelp site} (AWS S3 SSL); generated from DITA XML
|
||||
source files, which can be found in @uref{https://dev.gnupg.org/source/gpgme/browse/ben%252Fhowto-dita/, an alternative branch} of the GPGME
|
||||
git repository.
|
||||
|
||||
Various generated output formats may occasionally be found in
|
||||
subdirectories of the @uref{https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python, gpgme-python} directory. In particular within
|
||||
the @uref{https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/dita, DITA}, @uref{https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/rst, reStructuredText} and @uref{https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/texinfo, Texinfo} subdirectories. The @samp{rst}
|
||||
directory contains output files generated with Sphix and may include a
|
||||
considerable number of its possible output formats.
|
||||
|
||||
These draft editions are not official documents and the version of
|
||||
documentation in the master branch or which ships with released
|
||||
versions is the only official documentation. Nevertheless, these
|
||||
|
||||
@ -29,6 +29,11 @@ Maintenance Mode from 2019
|
||||
|
||||
* Maintainer from 2019 onward::
|
||||
* Using the Python Bindings from 2019 and beyond::
|
||||
* Documentation formats::
|
||||
|
||||
Documentation formats
|
||||
|
||||
* Cautionary Notes regarding Sphinx and EPUB::
|
||||
|
||||
@end detailmenu
|
||||
@end menu
|
||||
@ -66,6 +71,7 @@ the bindings.
|
||||
@menu
|
||||
* Maintainer from 2019 onward::
|
||||
* Using the Python Bindings from 2019 and beyond::
|
||||
* Documentation formats::
|
||||
@end menu
|
||||
|
||||
@node Maintainer from 2019 onward
|
||||
@ -122,4 +128,42 @@ Those with a commercial interest in expediting such a feature request
|
||||
already know how to @uref{https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset, expedite it} (use the message field to state what
|
||||
feature is being requested).
|
||||
|
||||
@node Documentation formats
|
||||
@section Documentation formats
|
||||
|
||||
The documentation has been written in Org mode for GNU Emacs, with
|
||||
both Texinfo and reStructuredText formats generated from that. The
|
||||
Texinfo files are intended for use with the rest of the GnuPG
|
||||
documentation; while the reStructuredText files are intended for use
|
||||
with Docutils and Sphinx, as with other Python projects.
|
||||
|
||||
@menu
|
||||
* Cautionary Notes regarding Sphinx and EPUB::
|
||||
@end menu
|
||||
|
||||
@node Cautionary Notes regarding Sphinx and EPUB
|
||||
@subsection Cautionary Notes regarding Sphinx and EPUB
|
||||
|
||||
Though Python's Docutils in conjunction with Sphinx is capable of
|
||||
generating some very useful HTML sites, as proven by @uref{https://readthedocs.org/, Read the Docs} and
|
||||
the @uref{https://docs.python.org/, Python documentation}, there are a number of output formats it does
|
||||
not handle well. At the top of the list of things it manages to break
|
||||
so atrociously as to be embarassing is the @uref{http://idpf.org/epub, EPUB 3} format.
|
||||
|
||||
The automatically generated EPUB of the CPython documentation always
|
||||
contains hundreds of validation errors and even the modest amount of
|
||||
documentation here @uref{https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub, produced a file} with approximately thirty
|
||||
validation errors. As the volume of documentation content increases,
|
||||
so does the induced errors. Whereas Texinfo doesn't produce EPUB
|
||||
output at all, nor does Org-mode.
|
||||
|
||||
Should there ever be genuine demand for this format, lodge a @uref{https://dev.gnupg.org/maniphest/task/edit/form/4/, feature
|
||||
request} case marked for @uref{https://dev.gnupg.org/p/BenM/, my} attention. The means of generating such
|
||||
files flawlessly is already available, but is not yet part of the
|
||||
GnuPG build system. Nor is it integrated with a means of converting
|
||||
Org mode input files to the relevant base format automatically, as can
|
||||
already be done when converting Org to reStructuredText or Org to
|
||||
Texinfo. As a certain amount of work would be required to get it
|
||||
done, there would need to be clear demand for that work to be done.
|
||||
|
||||
@bye
|
||||
Loading…
Reference in New Issue
Block a user