Hi, On Thu, 31 Jul 2025 13:51:07 +0200, Mauro Carvalho Chehab wrote: > Em Tue, 8 Jul 2025 23:56:01 +0900 > Akira Yokosawa <akiyks@xxxxxxxxx> escreveu: > >> I've been ignoring sphinx-pre-install all these years, but the impressive >> test results presented in this cover-letter made me test it. > > I'm now working to fix PDF generation, assuming that all packages from > sphinx-pre-install are installed. > > I'm placing the patches on my scratch tree at: > https://github.com/mchehab/linux/tree/my-docs-next > > It contains several branches merged there in sequence: > - elder_python_v1: makes kernel-doc run with elder kernels (2 patches); > - netlink_v10: patches adding an yaml parser for netlink (14 patches); > - sphinx-pre-install-v4: current version of this series (39 patches); > - pdfdocs: specific fixes for PDF doc generation (11 patches); > - sphinx-build-wrapper: a new script with a large cleanup at docs Makefile > (7 patches) Sorry, but I've not looked into those branches. [...] > So, at least for me, it seems that the changes will be fixing > lots of existing issues. > > Btw, one of the problem with PDFs is that the existing logic > doesn't really report success/failures for each PDF target. > That's why I ended writing a wrapper (sphinx-build-wrapper) with > checks the results. As a side effect, docs Makefile is now in > sane state. I might be interested in seeing the docs Makefile updates. > > Thanks, > Mauro > > --- [...] > Summary > ======= > PASSED - AlmaLinux release 9.6 (Sage Margay) (7 tests) > PASSED - Amazon Linux release 2023 (Amazon Linux) (7 tests) > PASSED - Arch Linux (7 tests) > PASSED - CentOS Stream release 9 (7 tests) > PARTIAL - Debian GNU/Linux 12 (7 tests) > PARTIAL - Devuan GNU/Linux 5 (7 tests) > PASSED - Fedora release 42 (Adams) (7 tests) > PARTIAL - Gentoo Base System release 2.17 (7 tests) > PASSED - Kali GNU/Linux 2025.2 (7 tests) > PASSED - Mageia 9 (7 tests) > PARTIAL - Linux Mint 22 (7 tests) > PARTIAL - openEuler release 25.03 (7 tests) > PARTIAL - OpenMandriva Lx 4.0 (7 tests) > PASSED - openSUSE Leap 15.6 (7 tests) > PASSED - openSUSE Tumbleweed (7 tests) > PASSED - Oracle Linux Server release 9.6 (7 tests) > FAILED - Red Hat Enterprise Linux release 8.10 (Ootpa) (7 tests) > FAILED - rockylinux8 (1 tests) > PASSED - Rocky Linux release 9.6 (Blue Onyx) (7 tests) > FAILED - Springdale Open Enterprise Linux release 9.2 (Parma) (7 tests) > PASSED - Ubuntu 24.04.2 LTS (7 tests) > PASSED - Ubuntu 25.04 (7 tests) Here is a summary I have made based on my own tests against limited list of distros. I'm still ignoring sphinx_pre_install. ----------------------------------------------------------------------- * TL;DR Setting up a tool for SVG --> PDF conversion and CJK fonts properly for "make latexdocs" and "make pdfdocs" is sometimes tricky. Summary table as of 2025/08/02 WRT distro packages installed as they are: [legends] pdf & img: pdfdocs with ImageMagick + rsvg-convert; w/o CJK fonts pdf & ink: pdfdocs with Inkscape; w/o CJK fonts pdf & cjk: pdfdocs with either ImageMagick or Inkscape; with CJK fonts ======================================================================== pdf ----------------- distro python3 sphinx html img ink cjk notes =================== ======= ======= ===== ===== ===== ===== ========= debian:bullseye 3.9.2 3.4.3 PASS FAIL PASS PASS [*0] debian:bookworm 3.11.2 5.3.0 PASS FAIL PASS PASS [*0] debian:trixie 3.13.5 8.1.3 PASS FAIL PASS PASS [*6] ubuntu:jammy 3.10.6 4.3.2 PASS FAIL PASS PASS [*0] ubuntu:noble 3.12.3 7.2.6 PASS FAIL PASS PASS [*6] ubuntu:plucky 3.13.3 8.1.3 PASS FAIL PASS PASS [*6] almalinux:9 3.9.21 3.4.3 PASS PASS PASS PASS almalinux:10 3.12.9 7.2.6 PASS PASS --- FAIL [*1] fedora:42 3.13.5 8.1.3 PASS PASS PASS PASS [*2] opensuse/leap:15.6 3.11.9 7.2.6 PASS PASS FAIL FAIL [*3] mageia:9 3.10.11 6.1.3 PASS PASS PASS PASS [*4] opensuse/tumbleweed 3.13.5 8.2.3 PASS PASS PASS FAIL [*5] archlinux 3.13.5 8.2.3 PASS PASS PASS PASS =================== ======= ======= ===== ===== ===== ===== ========== "FAIL" means several situations, most of which can be worked around by manual intervention after installing distro packages: (1) error/warning in "make latexdocs" (1-a) due to some issues in distro package that is not up-to-date (1-b) convert(1) of ImageMagick doesn't generate PDFs with the warning: WARNING: Warning msg from convert(1): convert: attempt to perform an operation not allowed by the security policy `PDF' ... (1-c) Incompatibility of newly added SVG figures with avalable SVG --> PDF converters: (1-c1) covert(1) + rsvg-convert(1) (1-c2) inkscape(1) (2) error in "make pdfdocs" (2-a) (1-b) or (1-c) can cause "LaTeX Warning: Float too large for page by <huge>pt" and ends up in the fatal error of xelatex: "! TeX capacity exceeded, sorry [main memory size=5000000]" (2-b) (1-b) or (1-c) can cause xelatex to error-exit without leaving any hint in the .log file. (3) CJK pages can't be rendered (3-a) due to missing *static* Noto CJK fonts in distro packages Notes ===== [*0] ImageMagick is not allowed to generate PDFs in Debian and its derivative releases prior to ubuntu:noble. [*1] An issue in cairo prevents a DOT diagram in a CJK page to be converted into PDF ("dot -Tpdf" crash; known issue with cairo-1.18.2-2.el10). Inkscape is not in EPEL 10. Use of flatpak is recommended for GUI apps, but flatpak apps don't see font setups of hosts by default. Serif shape Static Noto CJK fonts are not provided as distro packages. [*2] Due to a xelatex & fontspec limitation, if you have variable Noto CJK fonts installed, they need to be deny-listed for building PDF docs with CJK fonts. [*3] Sphinx 7.2.6 is provided as python311-Sphinx. Inkscape 1.0.1 crashes against figures drawn with Inkscape 1.4.x. Noto CJK fonts are not provided as distro packages. [*4] When Inkscape is available, their parallel runs under Gnome desktop can cause emergency saves of SVG files. This issue can be worked around by, e.g., building under a text-only session or a non-Gnome desktop. [*5] Static Noto CJK fonts are not provided as distro packages. Even if they are manually installed from Google fonts manually, deny-listing distro-provided variable ones is required for CJK pages. [*6] convert(1) + rsvg_convert(1) doesn't work well with some SVG files under recent debian and its derivatives. Incomplete list of examples: - Documentation/gpu/pipe_and_queue_abstraction.svg: convert: unrecognized color `context-stroke' @ warning/color.c/GetColorCompliance/1057. convert: non-conforming drawing primitive definition `fill' @ error/draw.c/RenderMVGContent/4456. - Documentation/userspace-api/media/v4l/selection.svg: convert: unrecognized color `dt' @ warning/color.c/GetColorCompliance/1064. convert: non-conforming drawing primitive definition `fill' @ error/draw.c/RenderMVGContent/4548. convert: unrecognized color `w' @ warning/color.c/GetColorCompliance/1064. convert: unrecognized color `dt' @ warning/color.c/GetColorCompliance/1064. convert: unrecognized color `w' @ warning/color.c/GetColorCompliance/1064. [about almalinux:8] There is a package python3.11, but there is no accompanying package for virtualenv in official EL 8 repos. It might be possible to install python3.11 as well as accompanying pip and pyyaml, and install modern Sphinx by non-venv pip. This might be feasible, e.g., in containerized setups. On top of almalinux:8, as far as I could test, xelatex & fontspec can't discover fonts by its names such as "DejaVu Sans". ----------------------------------------------------------------------- Thanks, Akira
