[PATCH 0/3] Drop another script used during doc builds

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Hi Jon,

Heh, with all those scripts and hacks that were accumulated with time
for docs makefile, placing them there with absolutely no documentation,
I ended missing scripts/check-variable-fonts.sh.

I only realized today when searching for the "|| exit" hack we added
in 2017 to fix an issue where make pdfdocs were always returning
errors (again, not documented).

This series comes after(*):

    https://lore.kernel.org/linux-doc/cover.1757677427.git.mchehab+huawei@kernel.org/T/#t

(*) I should probably have named such series as:
    "Move the trick-or-treat build hacks accumulated over time into a single place and document them."

This specific script is called only when PDF build fails. Re-add
it at sphinx-build-wrapper logic. After it, problematic PDF
builds will warn again about possible issues with CJK variable
fonts:

	$ make SPHINXDIRS=translations pdfdocs

	Summary
	=======
	translations: FAILED

	=============================================================================
	XeTeX is confused by "variable font" files listed below:
	    /usr/share/fonts/google-noto-sans-cjk-vf-fonts/NotoSansCJK-VF.ttc
	    /usr/share/fonts/google-noto-sans-mono-cjk-vf-fonts/NotoSansMonoCJK-VF.ttc
	    /usr/share/fonts/google-noto-serif-cjk-vf-fonts/NotoSerifCJK-VF.ttc

	For CJK pages in PDF, they need to be hidden from XeTeX by denylisting.
	Or, CJK pages can be skipped by uninstalling texlive-xecjk.

	For more info on denylisting, other options, and variable font, see header
	comments of tools/docs/lib/latex_fonts.py.
	=============================================================================
	PDF build failed: not all PDF files were created.
	make[2]: *** [Documentation/Makefile:58: pdfdocs] Error 1
	make[1]: *** [/new_devel/docs/Makefile:1806: pdfdocs] Error 2
	make: *** [Makefile:248: __sub-make] Error 2

The output message is identical, except that it now uses __file__ to get the
actual location of the verify code (which is now part of a docs lib).

All comments from the original code were preserved, but I opted to use
python docstring to store it. This way, we may even add something like
print(__doc__) in the future, if needed.

I also opted to preserve a command-line interface, which does nothing but
call the check function:

	$ ./tools/docs/check-variable-fonts.py
	=============================================================================
	XeTeX is confused by "variable font" files listed below:
	    /usr/share/fonts/google-noto-sans-cjk-vf-fonts/NotoSansCJK-VF.ttc
	    /usr/share/fonts/google-noto-sans-mono-cjk-vf-fonts/NotoSansMonoCJK-VF.ttc
	    /usr/share/fonts/google-noto-serif-cjk-vf-fonts/NotoSerifCJK-VF.ttc

	For CJK pages in PDF, they need to be hidden from XeTeX by denylisting.
	Or, CJK pages can be skipped by uninstalling texlive-xecjk.

	For more info on denylisting, other options, and variable font, see header
	comments of tools/docs/lib/latex_fonts.py.
	=============================================================================

I opted to place it into a class, as we can one day add more functions there,
for instance to create the proposed XML file under ~/deny-vc, as the script's
documentation proposes.

By using a class, we only need to import the class: all functions from
such class are automatically imported altogether. Plus, we don't have to
deal with namespaces for a function called "check()".

Mauro Carvalho Chehab (3):
  scripts/check-variable-fonts.sh: convert to Python
  scripts: check-variable-fonts.py: split into a lib and an exec file
  tools/docs: sphinx-build-wrapper: warn about broken PDF fonts

 MAINTAINERS                        |   1 -
 scripts/check-variable-fonts.sh    | 115 --------------------
 tools/docs/check-variable-fonts.py |  23 ++++
 tools/docs/lib/latex_fonts.py      | 162 +++++++++++++++++++++++++++++
 tools/docs/sphinx-build-wrapper    |   9 +-
 5 files changed, 192 insertions(+), 118 deletions(-)
 delete mode 100755 scripts/check-variable-fonts.sh
 create mode 100755 tools/docs/check-variable-fonts.py
 create mode 100755 tools/docs/lib/latex_fonts.py

-- 
2.50.1