linux/poky.git/documentation/conf.py, branch kirkstone-4.0.28

docs: conf.py: silence SyntaxWarning on js_splitter_code

2025-06-13T15:42:36+00:00

The js_splitter_code string contains backslashes that Python tries to use as escape sequence but doesn't manage to, hence the following SyntaxWarning message: documentation/conf.py:188: SyntaxWarning: invalid escape sequence '\p' .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}-]+/gu) Considering that we want this to be sent verbatim to the JS, let's make this a raw string instead. Fixes: d4a98ee19e0c ("conf.py: tweak SearchEnglish to be hyphen-friendly") (From yocto-docs rev: 92bc958301d0aeab0a19e75b8604f01770358195) Signed-off-by: Quentin Schulz Signed-off-by: Antonin Godard (cherry picked from commit c1056672ef45b197136eb8815728d426337a5901) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

conf.py: tweak SearchEnglish to be hyphen-friendly

2025-05-28T15:46:32+00:00

This modifies the default indexer split() and js splitQuery() methods to support searching for words with hyphens. While this might not be an ideal, rock solid, and fully future-proof solution, it allows at least to search for strings inlcuding hyphens, such as 'bitbake-layers', 'send-error-report', or 'oe-core'. Below is a bit more detailed explanation of the two modifications done: 1) The default split regex in the sphinx-doc SearchLanguage base class is: | _word_re = re.compile(r'\w+') which we simply extend to include hyphens '-'. This will result in a searchindex.js that contains words with hyphens, too. 2) The 'searchtool.js' code notes for its splitQuery() implementation: | /** | * Default splitQuery function. Can be overridden in ``sphinx.search`` with a | * custom function per language. | * | * The regular expression works by splitting the string on consecutive characters | * that are not Unicode letters, numbers, underscores, or emoji characters. | * This is the same as ``\W+`` in Python, preserving the surrogate pair area. | */ | if (typeof splitQuery === "undefined") { | var splitQuery = (query) => query | .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) | .filter(term => term) // remove remaining empty strings | } The hook for this is documented in the sphinx-docs 'SearchLanguage' base class. | .. attribute:: js_splitter_code | | Return splitter function of JavaScript version. The function should be | named as ``splitQuery``. And it should take a string and return list of | strings. | | .. versionadded:: 3.0 We use this to define a simplified splitQuery() function with a split argument that splits on empty spaces only. We extend SearchEnglish (which extends SearchLanguage) here to retain the stemmer code and stopwords for English. [YOCTO #14534] (From yocto-docs rev: 72e70a6af6eb3d4ca41f9e64069d8d3f61b420a3) Signed-off-by: Enrico Jörns Signed-off-by: Antonin Godard (cherry picked from commit d4a98ee19e0cbd6be96923dc72faee143a6b294b) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

Add favicon for the documentation html

2025-02-24T15:00:54+00:00

Import the favicon from https://www.yoctoproject.org/, convert it to 16x16 (as per the Sphinx documentation) to make a 1291B image of the Yocto logo. (From yocto-docs rev: 73119a723b48a4038479591f0443c5acb3d21337) Signed-off-by: Antonin Godard (cherry picked from commit e3ee43e6d70685a2404aae2d60557a42879b0bb1) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

Revert "doc: Makefile: add support for xelatex"

2024-11-15T14:51:25+00:00

This reverts commit 0a6944b9f90b4d3babbdec9dee18fb8195b0db06. (From yocto-docs rev: 08fae3c2dd1dbd898c028a4e713ca4d388ccee6b) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

conf.py: add a bitbake_git extlink

2024-11-15T14:05:32+00:00

To make references to the bitbake repo, add an extlink for it and use it in the docs with ":bitbake_git:`lib/bb/utils.py `". Reviewed-by: Quentin Schulz (From yocto-docs rev: 579da2e7222c1bd21948205f470d97435f3b2cc3) Signed-off-by: Antonin Godard (cherry picked from commit 8bf3c656ec54a582c75ca7c135121a15f8e4f631) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

doc: Makefile: add support for xelatex

2024-11-15T14:05:32+00:00

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. (From yocto-docs rev: 0a6944b9f90b4d3babbdec9dee18fb8195b0db06) Signed-off-by: Antonin Godard (cherry picked from commit 93848842b3ad8aa6b9c9f46d60f2c2ad396c6971) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

conf.py: rename :cve: role to :cve_nist:

2024-11-11T14:19:19+00:00

Newer versions of Sphinx already define a :cve: role that points to cve.org, instead of the role we defined in conf.py that points to nvd.nist.gov. Rename our role to :cve_nist: to avoid warnings (treated as errors). This is also backwards compatible, meaning we can build the doc with an older Sphinx if needed. The file were automatically replaced with following command: find . -name '*.rst' -exec sed -i 's/:cve:/:cve_nist:/g' {} \+ Cherry pick: * Changes on following files removed from cherry pick (not part of kirkstone): documentation/migration-guides/release-notes-4.1.1.rst documentation/migration-guides/release-notes-4.1.2.rst documentation/migration-guides/release-notes-4.1.3.rst documentation/migration-guides/release-notes-4.1.4.rst documentation/migration-guides/release-notes-4.1.rst documentation/migration-guides/release-notes-4.2.1.rst documentation/migration-guides/release-notes-4.2.2.rst documentation/migration-guides/release-notes-4.2.3.rst documentation/migration-guides/release-notes-4.2.4.rst documentation/migration-guides/release-notes-4.2.rst documentation/migration-guides/release-notes-4.3.1.rst documentation/migration-guides/release-notes-4.3.2.rst documentation/migration-guides/release-notes-4.3.3.rst documentation/migration-guides/release-notes-4.3.4.rst documentation/migration-guides/release-notes-4.3.rst documentation/migration-guides/release-notes-5.0.2.rst documentation/migration-guides/release-notes-5.0.3.rst documentation/migration-guides/release-notes-5.0.rst documentation/migration-guides/release-notes-5.1.rst * Fix minor conflicts in following files: documentation/migration-guides/release-notes-3.4.2.rst: missing :term: before CVE_PRODUCT documentation/migration-guides/release-notes-4.0.2.rst: missing :term: before PACKAGECONFIG documentation/migration-guides/release-notes-4.0.7.rst: missing cve 2022-32912 on webkitgtk Suggested-By: Quentin Schulz Reviewed-by: Quentin Schulz (From yocto-docs rev: f432e78fef82c5e5bfdfff08bb18757dc3479465) Signed-off-by: Antonin Godard (cherry picked from commit 15fa3b7e85dde50d7236c1738ad607531cc654b8) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

docs: conf.py: properly escape backslashes for latex_elements

2024-04-19T11:50:39+00:00

There are some syntax warnings returned by Python: """ yocto-docs/documentation/conf.py:162: SyntaxWarning: invalid escape sequence '\P' 'passoptionstopackages': '\PassOptionsToPackage{bookmarksdepth=5}{hyperref}', yocto-docs/documentation/conf.py:163: SyntaxWarning: invalid escape sequence '\s' 'preamble': '\setcounter{tocdepth}{2}', """ Backslashes must be doubled in Python string literals to avoid interpretation as escape sequence, c.f. https://www.sphinx-doc.org/en/master/latex.html#module-latex. Cc: Quentin Schulz (From yocto-docs rev: 037f99339a4bae60f41f89df37911690b507c9a1) Signed-off-by: Quentin Schulz Reviewed-by: Michael Opdenacker Signed-off-by: Steve Sakoman

conf.py: add macro for Mitre CVE links

2023-05-30T14:11:16+00:00

New cve_mitre macro for CVEs that are not found (yet) on https://nvd.nist.gov/ (From yocto-docs rev: ff675ce150187561d6d1e8b8ff0eeb10b2696ec6) Signed-off-by: Michael Opdenacker Signed-off-by: Steve Sakoman

Revert "docs: conf.py: fix cve extlinks caption for sphinx <4.0"

2023-05-30T14:11:16+00:00

This reverts commit c9922076f5c1285d9cfd6aff8ce5b6635d88222f. Since the minimum version required to build the docs has been bumped in the previous commit to 4.0, this commit is not required. Moreover, since Sphinx 5.0 triggers a warning when extlinks captions are not using %s substitution and Sphinx 6.0 will fail to build without the substitution characters, this revert is now required to be able to build the docs. Cc: Quentin Schulz (From yocto-docs rev: 444df054f0bf3ad7614e1613b22ee5b9e8cb94ef) Signed-off-by: Quentin Schulz Signed-off-by: Richard Purdie Signed-off-by: Steve Sakoman