From 1e265723653042bc1010b457537b69a2011b43b7 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Sun, 27 Jan 2019 14:57:53 +1100 Subject: python: post installer docs fix script * Moved post_installer.py into the examples/howto/ directory. * Added instructions for its use to the Python Bindings HOWTO. * Ran it as intended from the lang/python/ directory in order to both prove it works and quickly and easily get the updated howto replicated. Also to fix all those .texi files. Tested-by: Ben McGinnes Signed-off-by: Ben McGinnes --- lang/python/doc/rst/gpgme-python-howto.rst | 15 +++ lang/python/doc/rst/index.rst | 10 +- lang/python/doc/src/gpgme-python-howto | 16 +++ lang/python/doc/texinfo/gpgme-python-howto.texi | 17 ++- lang/python/doc/texinfo/index.texi | 2 +- lang/python/doc/texinfo/maintenance-mode.texi | 2 +- lang/python/doc/texinfo/short-history.texi | 2 +- lang/python/doc/texinfo/what-is-new.texi | 2 +- lang/python/doc/texinfo/what-was-new.texi | 2 +- lang/python/examples/howto/post_installer.py | 147 ++++++++++++++++++++++++ lang/python/post_installer.py | 147 ------------------------ 11 files changed, 200 insertions(+), 162 deletions(-) create mode 100755 lang/python/examples/howto/post_installer.py delete mode 100755 lang/python/post_installer.py (limited to 'lang/python') diff --git a/lang/python/doc/rst/gpgme-python-howto.rst b/lang/python/doc/rst/gpgme-python-howto.rst index 4146e374..5f8bcd5d 100644 --- a/lang/python/doc/rst/gpgme-python-howto.rst +++ b/lang/python/doc/rst/gpgme-python-howto.rst @@ -683,6 +683,21 @@ on the system and version of Python in use. Another option is to run the command ``python3 -m virtualenv /path/to/install/virtual/thingy`` instead. +.. _snafu-docs: + +Post installation +~~~~~~~~~~~~~~~~~ + +Following installation it is recommended to move the +``post_installer.py`` script from the ``lang/python/examples/howto/`` +directory to the ``lang/python/`` directory and run it. This will fix or +restore files needed by Sphinx which may be removed during a +distribution build for release. It will also generate reST files from +Org mode files with Pandoc and generate Texinfo files from Org mode +files with GNU Emacs and Org mode (in batch mode). Additionally it will +fix the UTF-8 declaration line in the Texinfo files (Emacs expects +\"UTF-8\" to be \"utf-8\"). + .. _howto-fund-a-mental: Fundamentals diff --git a/lang/python/doc/rst/index.rst b/lang/python/doc/rst/index.rst index 9c4f0f7a..3ff34fc4 100644 --- a/lang/python/doc/rst/index.rst +++ b/lang/python/doc/rst/index.rst @@ -7,7 +7,7 @@ GPGME Python Bindings ===================== .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: Contents: Contents @@ -20,11 +20,3 @@ Contents - `What Was New `__ - `GPGME Python Bindings HOWTO `__ - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto index 6569806b..c63191b4 100644 --- a/lang/python/doc/src/gpgme-python-howto +++ b/lang/python/doc/src/gpgme-python-howto @@ -705,6 +705,22 @@ the command =python3 -m virtualenv /path/to/install/virtual/thingy= instead. +*** Post installation + :PROPERTIES: + :CUSTOM_ID: snafu-docs + :END: + +Following installation it is recommended to move the +=post_installer.py= script from the =lang/python/examples/howto/= +directory to the =lang/python/= directory and run it. This will fix +or restore files needed by Sphinx which may be removed during a +distribution build for release. It will also generate reST files from +Org mode files with Pandoc and generate Texinfo files from Org mode +files with GNU Emacs and Org mode (in batch mode). Additionally it +will fix the UTF-8 declaration line in the Texinfo files (Emacs +expects "UTF-8" to be "utf-8"). + + * Fundamentals :PROPERTIES: :CUSTOM_ID: howto-fund-a-mental diff --git a/lang/python/doc/texinfo/gpgme-python-howto.texi b/lang/python/doc/texinfo/gpgme-python-howto.texi index fac0056f..9f53aa5a 100644 --- a/lang/python/doc/texinfo/gpgme-python-howto.texi +++ b/lang/python/doc/texinfo/gpgme-python-howto.texi @@ -81,6 +81,7 @@ Known Issues * Won't Work With Windows:: * CFFI is the Best™ and GPGME should use it instead of SWIG:: * Virtualised Environments:: +* Post installation:: Fundamentals @@ -511,6 +512,7 @@ they be encountered. * Won't Work With Windows:: * CFFI is the Best™ and GPGME should use it instead of SWIG:: * Virtualised Environments:: +* Post installation:: @end menu @node Breaking Builds @@ -883,6 +885,19 @@ on the system and version of Python in use. Another option is to run the command @samp{python3 -m virtualenv /path/to/install/virtual/thingy} instead. +@node Post installation +@subsection Post installation + +Following installation it is recommended to move the +@samp{post_installer.py} script from the @samp{lang/python/examples/howto/} +directory to the @samp{lang/python/} directory and run it. This will fix +or restore files needed by Sphinx which may be removed during a +distribution build for release. It will also generate reST files from +Org mode files with Pandoc and generate Texinfo files from Org mode +files with GNU Emacs and Org mode (in batch mode). Additionally it +will fix the UTF-8 declaration line in the Texinfo files (Emacs +expects "UTF-8" to be "utf-8"). + @node Fundamentals @chapter Fundamentals @@ -3465,4 +3480,4 @@ WITHOUT ANY WARRANTY, to the extent permitted by law; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -@bye +@bye \ No newline at end of file diff --git a/lang/python/doc/texinfo/index.texi b/lang/python/doc/texinfo/index.texi index 0f4863c7..95c27c22 100644 --- a/lang/python/doc/texinfo/index.texi +++ b/lang/python/doc/texinfo/index.texi @@ -57,4 +57,4 @@ GPGME Python Bindings @uref{gpgme-python-howto, GPGME Python Bindings HOWTO} @end itemize -@bye +@bye \ No newline at end of file diff --git a/lang/python/doc/texinfo/maintenance-mode.texi b/lang/python/doc/texinfo/maintenance-mode.texi index d38875bd..92457190 100644 --- a/lang/python/doc/texinfo/maintenance-mode.texi +++ b/lang/python/doc/texinfo/maintenance-mode.texi @@ -166,4 +166,4 @@ 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 +@bye \ No newline at end of file diff --git a/lang/python/doc/texinfo/short-history.texi b/lang/python/doc/texinfo/short-history.texi index cbb13f31..d27f68d9 100644 --- a/lang/python/doc/texinfo/short-history.texi +++ b/lang/python/doc/texinfo/short-history.texi @@ -221,4 +221,4 @@ For those using Python 2, there is essentially no harm in using this module, but it may lack a number of more recent features added to GPGME. -@bye +@bye \ No newline at end of file diff --git a/lang/python/doc/texinfo/what-is-new.texi b/lang/python/doc/texinfo/what-is-new.texi index 5abc87a6..406ab2f7 100644 --- a/lang/python/doc/texinfo/what-is-new.texi +++ b/lang/python/doc/texinfo/what-is-new.texi @@ -91,4 +91,4 @@ repetition if a key includes a user ID matching the hexadecimal value of a key ID. @end itemize -@bye +@bye \ No newline at end of file diff --git a/lang/python/doc/texinfo/what-was-new.texi b/lang/python/doc/texinfo/what-was-new.texi index 29ea847c..3f0ad9d9 100644 --- a/lang/python/doc/texinfo/what-was-new.texi +++ b/lang/python/doc/texinfo/what-was-new.texi @@ -157,4 +157,4 @@ the time). Cleaned up a lot of things under the hood. @end itemize -@bye +@bye \ No newline at end of file diff --git a/lang/python/examples/howto/post_installer.py b/lang/python/examples/howto/post_installer.py new file mode 100755 index 00000000..b9fd36f2 --- /dev/null +++ b/lang/python/examples/howto/post_installer.py @@ -0,0 +1,147 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +# Copyright (C) 2016-2018 g10 Code GmbH +# Copyright (C) 2015 Ben McGinnes +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +from __future__ import absolute_import, print_function, unicode_literals + +import glob +import os +import os.path +import shutil +import subprocess +import sys +import sysconfig + +from shutil import which + +del absolute_import, print_function, unicode_literals + +try: + emacs = os.path.realpath(which("emacs")) +except TypeError as e: + emacs = None + +try: + makeinfo = os.path.realpath(which("makeinfo")) +except TypeError as e: + makeinfo = None + +try: + pandoc = os.path.realpath(which("pandoc")) +except TypeError as e: + pandoc = None + +try: + texinfo = os.path.realpath(which("texinfo")) +except TypeError as e: + texinfo = None + +docsrc = glob.glob('doc/src/**/*', recursive=True) + +for srcdoc in docsrc: + process = subprocess.Popen([emacs, srcdoc, "--batch", "-f", + "org-texinfo-export-to-texinfo", "--kill"], + stdout=subprocess.PIPE) + procom = process.communicate() + +doctexi1 = glob.glob('doc/src/**/*.texi', recursive=True) +doctexi2 = [] +doctexi3 = [] + +for texi in doctexi1: + doctexi2.append(os.path.realpath(texi)) + +for texdoc in doctexi2: + newtex = texdoc.replace("doc/src/", "doc/texinfo/") + doctexi3.append(newtex) + with open(texdoc, "r") as f: + badtex = f.read() + goodtex = badtex.replace("@documentencoding UTF-8\n", + "@documentencoding utf-8\n") + with open(newtex, "w") as f: + f.write(goodtex) + +for srcdoc in docsrc: + rstdoc = "{0}.rst".format(srcdoc.replace("doc/src/", "doc/rst/")) + process = subprocess.Popen([pandoc, "-f", "org", "-t", "rst+smart", "-o", + rstdoc, srcdoc], stdout=subprocess.PIPE) + procom = process.communicate() + +with open("doc/rst/index.rst", "r") as f: + genindex = f.readlines() + +indextop = ['.. GPGME Python Bindings documentation master file, created by\n', + ' sphinx-quickstart on Wed Dec 5 09:04:47 2018.\n', + ' You can adapt this file completely to your liking, but it should at least\n', + ' contain the root `toctree` directive.\n', '\n', + 'GPGME Python Bindings\n', '=====================\n', '\n', + '.. toctree::\n', ' :maxdepth: 3\n', ' :caption: Contents:\n', + '\n'] + +with open("doc/rst/index.rst", "w") as f: + for line in indextop: + f.write(line) + for line in genindex[5:]: + f.write(line) + +with open("doc/rst/Makefile", "w") as f: + f.write("""# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +""") + +info_path = os.path.realpath(sysconfig._PREFIX + "/share/info") +info_paths = os.environ["INFOPATH"].split(":") + +if info_paths.count(info_path) == 0: + info_paths.insert(0, info_path) +else: + pass + +for ipath in info_paths: + if os.path.exists(os.path.realpath(ipath)) is False: + info_paths.remove(ipath) + else: + pass + +print(""" +You may now build your preferred documentation format using either: + + 1. Sphinx in the doc/rst/ directory; and/or + 2. Texinfo or Makeinfo in the doc/texinfo/ directory. + +Alternatively the original Org mode source files can be found in the doc/src/ +directory. +""") diff --git a/lang/python/post_installer.py b/lang/python/post_installer.py deleted file mode 100755 index b9fd36f2..00000000 --- a/lang/python/post_installer.py +++ /dev/null @@ -1,147 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- - -# Copyright (C) 2016-2018 g10 Code GmbH -# Copyright (C) 2015 Ben McGinnes -# -# This library is free software; you can redistribute it and/or -# modify it under the terms of the GNU Lesser General Public -# License as published by the Free Software Foundation; either -# version 2.1 of the License, or (at your option) any later version. -# -# This library is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# Lesser General Public License for more details. -# -# You should have received a copy of the GNU Lesser General Public -# License along with this library; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - -from __future__ import absolute_import, print_function, unicode_literals - -import glob -import os -import os.path -import shutil -import subprocess -import sys -import sysconfig - -from shutil import which - -del absolute_import, print_function, unicode_literals - -try: - emacs = os.path.realpath(which("emacs")) -except TypeError as e: - emacs = None - -try: - makeinfo = os.path.realpath(which("makeinfo")) -except TypeError as e: - makeinfo = None - -try: - pandoc = os.path.realpath(which("pandoc")) -except TypeError as e: - pandoc = None - -try: - texinfo = os.path.realpath(which("texinfo")) -except TypeError as e: - texinfo = None - -docsrc = glob.glob('doc/src/**/*', recursive=True) - -for srcdoc in docsrc: - process = subprocess.Popen([emacs, srcdoc, "--batch", "-f", - "org-texinfo-export-to-texinfo", "--kill"], - stdout=subprocess.PIPE) - procom = process.communicate() - -doctexi1 = glob.glob('doc/src/**/*.texi', recursive=True) -doctexi2 = [] -doctexi3 = [] - -for texi in doctexi1: - doctexi2.append(os.path.realpath(texi)) - -for texdoc in doctexi2: - newtex = texdoc.replace("doc/src/", "doc/texinfo/") - doctexi3.append(newtex) - with open(texdoc, "r") as f: - badtex = f.read() - goodtex = badtex.replace("@documentencoding UTF-8\n", - "@documentencoding utf-8\n") - with open(newtex, "w") as f: - f.write(goodtex) - -for srcdoc in docsrc: - rstdoc = "{0}.rst".format(srcdoc.replace("doc/src/", "doc/rst/")) - process = subprocess.Popen([pandoc, "-f", "org", "-t", "rst+smart", "-o", - rstdoc, srcdoc], stdout=subprocess.PIPE) - procom = process.communicate() - -with open("doc/rst/index.rst", "r") as f: - genindex = f.readlines() - -indextop = ['.. GPGME Python Bindings documentation master file, created by\n', - ' sphinx-quickstart on Wed Dec 5 09:04:47 2018.\n', - ' You can adapt this file completely to your liking, but it should at least\n', - ' contain the root `toctree` directive.\n', '\n', - 'GPGME Python Bindings\n', '=====================\n', '\n', - '.. toctree::\n', ' :maxdepth: 3\n', ' :caption: Contents:\n', - '\n'] - -with open("doc/rst/index.rst", "w") as f: - for line in indextop: - f.write(line) - for line in genindex[5:]: - f.write(line) - -with open("doc/rst/Makefile", "w") as f: - f.write("""# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -""") - -info_path = os.path.realpath(sysconfig._PREFIX + "/share/info") -info_paths = os.environ["INFOPATH"].split(":") - -if info_paths.count(info_path) == 0: - info_paths.insert(0, info_path) -else: - pass - -for ipath in info_paths: - if os.path.exists(os.path.realpath(ipath)) is False: - info_paths.remove(ipath) - else: - pass - -print(""" -You may now build your preferred documentation format using either: - - 1. Sphinx in the doc/rst/ directory; and/or - 2. Texinfo or Makeinfo in the doc/texinfo/ directory. - -Alternatively the original Org mode source files can be found in the doc/src/ -directory. -""") -- cgit v1.2.3