[PATCH 0/5] Add support for PDF/Epub generation

[PATCH 0/5] Add support for PDF/Epub generation

[Antonin Godard]

This patch series includes commits that enable PDF and Epub generation
during `make publish` and that includes them in the sidebar as a new
"Documentation Downloads" section. The files can be downloaded directly
from there and are displayed as a list in this page.

Example outputs:

- PDF: https://lufi.bootlin.com/r/PBq0qGTwBy#6JIczWeLiAjcwn9udqAeTaoHuZhoXq6sL/vpktteg5w=
- EPub: https://lufi.bootlin.com/r/_wRND0dvKD#88YA3opgX/CJTaGT3m5GxKBMBYeNfcR2VN3x7wnCU/E=

This patch series also changes the following:

- Don't use inkscape but rsvg-convert, a lighter tool for SVG conversion
  that can be included in a buildtools tarball.
- Build the PDF with xelatex instead of pdflatex, to support foreign
  characters (the pdf build is currently failing because of that).

On the autobuilder, the necessary was made to make texlive/xelatex and
so on available to the docs build (see run-docs-build).

The series also brings a change to switchers.js.in, to make the file
compatible with newer versions of Sphinx. Note: on the autobuilder, we
aim to build using the newer Sphinx (8.1.3).

I'm currently working on updating the dependency list in poky.yaml.in
(and where this file is used), but would like to send this series first
to have some feedback.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (4):
      doc: Makefile: remove inkscape, replace by rsvg-convert
      doc: Makefile: add support for xelatex
      doc: add a download page for epub and pdf
      sphinx-static/switchers.js.in: do not refer to URL_ROOT anymore

Michael Opdenacker (1):
      doc: Makefile: publish pdf and epub versions too

 documentation/Makefile                      | 17 +++++++++++------
 documentation/conf.py                       |  7 ++++++-
 documentation/downloads.rst                 | 11 +++++++++++
 documentation/index.rst                     |  7 +++++++
 documentation/sphinx-static/switchers.js.in |  6 ++++++
 5 files changed, 41 insertions(+), 7 deletions(-)
---
base-commit: bb472a7000672ce836573c3f2d3baf42cca01546
change-id: 20241010-pdf-xetex-06ac6b0f6b87

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>

[PATCH 1/5] doc: Makefile: remove inkscape, replace by rsvg-convert

[Antonin Godard]

Remove inkscape as it is not part of meta/, and use librsvg so we can
ship it in a buildtools tarball for the autobuilder workers.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/Makefile | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/documentation/Makefile b/documentation/Makefile
index 189bd1dfac69d3b3185aa3a2ff7c212084ae280b..d0333de2cb84ba648a64e51fd3711113788d6714 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -12,8 +12,8 @@ SOURCEDIR     = .
 IMAGEDIRS     = */svg
 BUILDDIR      = _build
 DESTDIR       = final
-SVG2PNG       = inkscape
-SVG2PDF       = inkscape
+SVG2PNG       = rsvg-convert
+SVG2PDF       = rsvg-convert
 
 ifeq ($(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi),0)
 $(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed")
@@ -40,11 +40,11 @@ PNGs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%.png,$(wildcard $(SOURCED
 
 # Pattern rule for converting SVG to PDF
 %.pdf : %.svg
-	$(SVG2PDF) --export-filename=$@ $<
+	$(SVG2PDF) --format=Pdf --output=$@ $<
 
 # Pattern rule for converting SVG to PNG
 %.png : %.svg
-	$(SVG2PNG) --export-filename=$@ $<
+	$(SVG2PNG) --format=Png --output=$@ $<
 
 clean:
 	@rm -rf $(BUILDDIR) $(PNGs) $(PDFs) poky.yaml sphinx-static/switchers.js releases.rst

-- 
2.46.1

[PATCH 2/5] doc: Makefile: add support for xelatex

[Antonin Godard]

This patch makes the "latexpdf" target compile the documentation with
xelatex instead of the default pdflatex engine.

The reason behind this is stated in [YOCTO #14357]: pdflatex does not
support compiling foreign characters, so we need to resort to another
engine, here xelatex.

It also increases the texmf config buf_size to 10000000 to avoid a
compilation error.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/Makefile | 5 ++++-
 documentation/conf.py  | 7 ++++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/documentation/Makefile b/documentation/Makefile
index d0333de2cb84ba648a64e51fd3711113788d6714..12ca2f95f6578a31cd309f80b58a2702561a6b9f 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -60,9 +60,12 @@ epub: $(PNGs)
 	$(SOURCEDIR)/set_versions.py
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+# Note: we need to pass buf_size here (which is also configurable from
+# texmf.cnf), to avoid following error:
+#   Unable to read an entire line---bufsize=200000. Please increase buf_size in texmf.cnf.
 latexpdf: $(PDFs)
 	$(SOURCEDIR)/set_versions.py
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	buf_size=10000000 $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 all: html epub latexpdf
 
diff --git a/documentation/conf.py b/documentation/conf.py
index 9e87df0564c1e93140bce8705d9b45f75cbded58..c7dd4e03fc0e99176a0fa2f74fda58efaf0af9b2 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -158,9 +158,14 @@ html_last_updated_fmt = '%b %d, %Y'
 # Remove the trailing 'dot' in section numbers
 html_secnumber_suffix = " "
 
+# We need XeTeX to process special unicode character, sometimes the contributor
+# list from the release note contains those.
+# See https://docs.readthedocs.io/en/stable/guides/pdf-non-ascii-languages.html.
+latex_engine = 'xelatex'
+latex_use_xindy = False
 latex_elements = {
     'passoptionstopackages': '\\PassOptionsToPackage{bookmarksdepth=5}{hyperref}',
-    'preamble': '\\setcounter{tocdepth}{2}',
+    'preamble': '\\usepackage[UTF8]{ctex}\n\\setcounter{tocdepth}{2}',
 }
 
 # Make the EPUB builder prefer PNG to SVG because of issues rendering Inkscape SVG

-- 
2.46.1

[PATCH 3/5] doc: Makefile: publish pdf and epub versions too

[antonin.godard]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Copy the generated files in the special _static directory.

Fixes [YOCTO #14357]

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/Makefile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/documentation/Makefile b/documentation/Makefile
index 12ca2f95f6578a31cd309f80b58a2702561a6b9f..ef5a6ce33987e8a79a65ac400212f877b7daf11e 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -25,10 +25,12 @@ help:
 
 .PHONY: all help Makefile clean stylecheck publish epub latexpdf
 
-publish: Makefile html singlehtml
+publish: Makefile epub latexpdf html singlehtml
 	rm -rf $(BUILDDIR)/$(DESTDIR)/
 	mkdir -p $(BUILDDIR)/$(DESTDIR)/
 	cp -r $(BUILDDIR)/html/* $(BUILDDIR)/$(DESTDIR)/
+	mkdir -p $(BUILDDIR)/$(DESTDIR)/_static
+	cp $(BUILDDIR)/epub/TheYoctoProject.epub $(BUILDDIR)/latex/theyoctoproject.pdf $(BUILDDIR)/$(DESTDIR)/_static/
 	cp $(BUILDDIR)/singlehtml/index.html $(BUILDDIR)/$(DESTDIR)/singleindex.html
 	sed -i -e 's@index.html#@singleindex.html#@g' $(BUILDDIR)/$(DESTDIR)/singleindex.html
 

-- 
2.46.1

[PATCH 4/5] doc: add a download page for epub and pdf

[Antonin Godard]

These files are placed in the _static directory during publish. Note
that Sphinx does not complain if files do not exist during compilation
(since they are copied at the end). This is why this was used instead of
the ":download:" role.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/downloads.rst | 11 +++++++++++
 documentation/index.rst     |  7 +++++++
 2 files changed, 18 insertions(+)

diff --git a/documentation/downloads.rst b/documentation/downloads.rst
new file mode 100644
index 0000000000000000000000000000000000000000..7ec978ef2da80c33f4e3b2aab47320ef01973187
--- /dev/null
+++ b/documentation/downloads.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+=======================
+Documentation Downloads
+=======================
+
+The documentation can be downloaded in file formats to be read offline or on
+another device. The currently supported formats are linked below:
+
+-  `EPub <_static/TheYoctoProject.epub>`_
+-  `PDF <_static/theyoctoproject.pdf>`_
diff --git a/documentation/index.rst b/documentation/index.rst
index 3fef1704a481da9e5e4c697a8efa995525ae5e6a..6c6be38a7e8c46bcc910d14abdc18f78b200c399 100644
--- a/documentation/index.rst
+++ b/documentation/index.rst
@@ -51,3 +51,10 @@ Welcome to the Yocto Project Documentation
    :hidden:
 
    genindex
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Documentation Downloads
+   :hidden:
+
+   downloads

-- 
2.46.1

[PATCH 5/5] sphinx-static/switchers.js.in: do not refer to URL_ROOT anymore

[Antonin Godard]

This variable was removed from the Sphinx-generated
documentation_options.js, thus breaking the current implementation of
our switchers.js. Like searchtools.js, which is also generated by
Sphinx, use document.documentElement.dataset.content_root as a
replacement.

To be backwards-compatible to get one or the other.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/sphinx-static/switchers.js.in | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/documentation/sphinx-static/switchers.js.in b/documentation/sphinx-static/switchers.js.in
index 8c016859bc80f03a6322bbea516864f75185c05a..b1c0812b53369b3c635e3466d84ca02f916d34f8 100644
--- a/documentation/sphinx-static/switchers.js.in
+++ b/documentation/sphinx-static/switchers.js.in
@@ -133,7 +133,13 @@ by https://git.yoctoproject.org/yocto-autobuilder-helper/tree/scripts/run-docs-b
 
   function get_docroot_url() {
     var url = window.location.href;
+    // Try to get the variable from documentation_options.js
     var root = DOCUMENTATION_OPTIONS.URL_ROOT;
+    if (root == null) {
+      // In recent versions of Sphinx, URL_ROOT was removed from
+      // documentation_options.js, so get it like searchtools.js does.
+      root = document.documentElement.dataset.content_root;
+    }
 
     var urlarray = url.split('/');
     // Trim off anything after '/'

-- 
2.46.1

Re: [PATCH 5/5] sphinx-static/switchers.js.in: do not refer to URL_ROOT anymore

[Gyorgy Sarvari]

[-- Attachment #1: Type: text/plain, Size: 298 bytes --]

It looks like that this patch got merged a while ago, but it seems that it is not online - at least not for Bitbake documentation. The top switcher is complaining that ' can't access property "match", root is undefined' , and when i inspect the issue, this commit seems to be missing from the js.

[-- Attachment #2: Type: text/html, Size: 612 bytes --]

Re: [docs] [PATCH 5/5] sphinx-static/switchers.js.in: do not refer to URL_ROOT anymore

[Antonin Godard]

Hi Gyorgy,

On Mon Oct 6, 2025 at 8:33 AM CEST, Gyorgy Sarvari via lists.yoctoproject.org wrote:
> It looks like that this patch got merged a while ago, but it seems that it is
> not online - at least not for Bitbake documentation. The top switcher is
> complaining that ' can't access property "match", root is undefined' , and
> when i inspect the issue, this commit seems to be missing from the js.

BitBake's documentation is lacking its own proper switchers.js for now. I had a
plan to fix it but I am lacking the time to finish the work.

I just pushed my local work on bitbake-contrib if you want to take a look:
https://git.openembedded.org/bitbake-contrib/log/?h=contrib/agodard/fix-switchers-js

The idea is that bitbake should have its own menu with its own versions and
switchers code. Help appreciated!

Also from which version of bitbake did you get this issue? A link to BB's docs
that reproduces the issue would help.

Thanks for the report,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH 5/5] sphinx-static/switchers.js.in: do not refer to URL_ROOT anymore

[Gyorgy Sarvari]

On 10/6/25 09:55, Antonin Godard via lists.yoctoproject.org wrote:
> Hi Gyorgy,
>
> On Mon Oct 6, 2025 at 8:33 AM CEST, Gyorgy Sarvari via lists.yoctoproject.org wrote:
>> It looks like that this patch got merged a while ago, but it seems that it is
>> not online - at least not for Bitbake documentation. The top switcher is
>> complaining that ' can't access property "match", root is undefined' , and
>> when i inspect the issue, this commit seems to be missing from the js.
> BitBake's documentation is lacking its own proper switchers.js for now. I had a
> plan to fix it but I am lacking the time to finish the work.
>
> I just pushed my local work on bitbake-contrib if you want to take a look:
> https://git.openembedded.org/bitbake-contrib/log/?h=contrib/agodard/fix-switchers-js

Sure, will take a look.

> The idea is that bitbake should have its own menu with its own versions and
> switchers code. Help appreciated!
>
> Also from which version of bitbake did you get this issue? A link to BB's docs
> that reproduces the issue would help.

I got this error here:
https://docs.yoctoproject.org/bitbake/2.12/bitbake-user-manual/bitbake-user-manual-ref-variables.html
- I wanted to switch to the Kirkstone docs, but it disagreed with me.

>
> Thanks for the report,
> Antonin
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#7645): https://lists.yoctoproject.org/g/docs/message/7645
> Mute This Topic: https://lists.yoctoproject.org/mt/109421245/6084445
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [skandigraun@gmail.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>

Re: [PATCH 0/5] Add support for PDF/Epub generation

[Richard Purdie]

On Wed, 2024-11-06 at 08:48 +0100, Antonin Godard wrote:
> This patch series includes commits that enable PDF and Epub generation
> during `make publish` and that includes them in the sidebar as a new
> "Documentation Downloads" section. The files can be downloaded directly
> from there and are displayed as a list in this page.
> 
> Example outputs:
> 
> - PDF: https://lufi.bootlin.com/r/PBq0qGTwBy#6JIczWeLiAjcwn9udqAeTaoHuZhoXq6sL/vpktteg5w=
> - EPub: https://lufi.bootlin.com/r/_wRND0dvKD#88YA3opgX/CJTaGT3m5GxKBMBYeNfcR2VN3x7wnCU/E=
> 
> This patch series also changes the following:
> 
> - Don't use inkscape but rsvg-convert, a lighter tool for SVG conversion
>   that can be included in a buildtools tarball.
> - Build the PDF with xelatex instead of pdflatex, to support foreign
>   characters (the pdf build is currently failing because of that).
> 
> On the autobuilder, the necessary was made to make texlive/xelatex and
> so on available to the docs build (see run-docs-build).
> 
> The series also brings a change to switchers.js.in, to make the file
> compatible with newer versions of Sphinx. Note: on the autobuilder, we
> aim to build using the newer Sphinx (8.1.3).
> 
> I'm currently working on updating the dependency list in poky.yaml.in
> (and where this file is used), but would like to send this series first
> to have some feedback.

FWIW I'm really happy to see this getting sorted out! The patches seem
reasonable to me.

Cheers,

Richard