Hi Jon,
Sorry for resending this one. Two e-mails ended being encoded
using base64 (*). The content of this series is identical. The
only difference is that all patches including 05 and 15 are now
in plain text (using 8bit encoding).
This series does a major cleanup at docs Makefile by moving the
actual doc build logic to a helper script (scripts/sphinx-build-wrapper).
Such script was written in a way that it can be called either
directly or via a makefile. When running via makefile, it will
use GNU jobserver to ensure that, when sphinx-build is
called, the number of jobs will match at most what it is
specified by the "-j" parameter.
The first 3 patches do a cleanup at scripts/jobserver-exec
and moves the actual code to a library. Such library is used
by both the jobserver-exec command line and by sphinx-build-wrappper.
The change also gets rid of parallel-wrapper.sh, whose
functions are now part of the wrapper code.
I added two patches at the end adding an extra target: "mandocs".
The patches came from a series I sent in separate with 2 patches.
---
(*) I just converted by internal mailbomb script to Python, but
EmailMessage is really tricky - I spent most of my time scratching
my head to get it right - It has a confusing set of "policy" rules
and two functions to generate messages. It turns that just using a
good policy is not enough: one needs to use as_bytes() to avoid
base64 encoding.
---
v3:
- rebased on the top of docs-next;
- added two patches to build man files that were on a separate
patch series.
v2:
- there's no generic exception handler anymore;
- it moves sphinx-pre-install to tools/docs;
- the logic which ensures a minimal Python version got moved
to a library, which is now used by both pre-install and wrapper;
- The first wrapper (05/13) doesn't contain comments (except for
shebang and SPDX). The goal is to help showing the size increase
when moving from Makefile to Python. Some file increase is
unavoidable, as Makefile is more compact: no includes, multple
statements per line, no argparse, etc;
- The second patch adds docstrings and comments. It has almost
the same size of the code itself;
- I moved the venv logic to a third wrapper patch;
- I fixed an issue at the paraller build logic;
- There are no generic except blocks anymore.
Mauro Carvalho Chehab (15):
scripts/jobserver-exec: move the code to a class
scripts/jobserver-exec: move its class to the lib directory
scripts/jobserver-exec: add a help message
scripts: sphinx-pre-install: move it to tools/docs
tools/docs: sphinx-pre-install: move Python version handling to lib
tools/docs: sphinx-build-wrapper: add a wrapper for sphinx-build
tools/docs: sphinx-build-wrapper: add comments and blank lines
tools/docs: sphinx-build-wrapper: add support to run inside venv
docs: parallel-wrapper.sh: remove script
docs: Makefile: document latex/PDF PAPER= parameter
tools/docs: sphinx-build-wrapper: add an argument for LaTeX
interactive mode
tools/docs,scripts: sphinx-*: prevent sphinx-build crashes
tools/docs: sphinx-build-wrapper: allow building PDF files in parallel
docs: add support to build manpages from kerneldoc output
tools: kernel-doc: add a see also section at man pages
Documentation/Makefile | 134 +---
Documentation/doc-guide/kernel-doc.rst | 29 +-
Documentation/sphinx/parallel-wrapper.sh | 33 -
Makefile | 2 +-
scripts/jobserver-exec | 88 +--
scripts/lib/jobserver.py | 149 +++++
scripts/lib/kdoc/kdoc_files.py | 5 +-
scripts/lib/kdoc/kdoc_output.py | 84 ++-
scripts/split-man.pl | 28 -
tools/docs/lib/python_version.py | 133 ++++
tools/docs/sphinx-build-wrapper | 731 +++++++++++++++++++++
{scripts => tools/docs}/sphinx-pre-install | 134 +---
12 files changed, 1194 insertions(+), 356 deletions(-)
delete mode 100644 Documentation/sphinx/parallel-wrapper.sh
create mode 100755 scripts/lib/jobserver.py
delete mode 100755 scripts/split-man.pl
create mode 100644 tools/docs/lib/python_version.py
create mode 100755 tools/docs/sphinx-build-wrapper
rename {scripts => tools/docs}/sphinx-pre-install (93%)
--
2.51.0
