linux/poky.git/documentation/conf.py, branch scarthgap-5.0.12

conf.py: improve SearchEnglish to handle terms with dots

2025-07-11T15:11:53+00:00

While search queries already handled words with hyphens correctly, they did not do so for words with dots. To fix this, we - enhance the word tokenizer to treat both dots ('.') and hyphens ('-') as valid characters within words. (For robustness, explicitly exclude dots/hyphens at the start or end of a word from indexing.) - adjust query processing to avoid splitting on dots in search input This allows search queries to correctly match terms such as 'local.conf', 'site.conf', and similar ones now. Fixes: [YOCTO #14534] (From yocto-docs rev: 3f88cb85cca8f9128cfaab36882c4563457b03d9) Signed-off-by: Enrico Jörns Signed-off-by: Antonin Godard (cherry picked from commit 80084a4cabdf7f61c7e93eda8ddbd5bc7d54e041) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

docs: conf.py: silence SyntaxWarning on js_splitter_code

2025-06-11T15:17:34+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: 6f424ed4ce749a135be3145a2e9d04030fdbda39) 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-27T16:38:57+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: ce18901b1059746069a0dea8893ba4a357772b51) 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

documentation/conf.py: define a manpage url

2025-04-28T15:18:53+00:00

By defining the manpages_url we can use the :manpage: role in the documentation for providing links to manpages. See: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url Replace existing manpages links to use this role. Reviewed-by: Quentin Schulz (From yocto-docs rev: 73faf4a4fdd3d536e8af92b49bf067746cd9fa05) Signed-off-by: Antonin Godard (cherry picked from commit 4e63cd74cd1a330ea5e96bb04243a90f607b2857) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

Add favicon for the documentation html

2025-02-21T14:25:06+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: 14de49a1ec6d725764e2a968edd3386252e826fe) Signed-off-by: Antonin Godard (cherry picked from commit e3ee43e6d70685a2404aae2d60557a42879b0bb1) Signed-off-by: Antonin Godard Signed-off-by: Steve Sakoman

conf.py: add a bitbake_git extlink

2024-11-18T14:59:35+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: f0e98d65e3dbdf7c9bed135285f21da8d084edc0) 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-18T14:59:35+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: 22f2365417ea5a9a7970e2475925f4f8eb983acf) 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-09T13:53:57+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: * remove changes to release-notes-5.1.rst, does not exist on this branch. * release-notes-5.0.4.rst: apply the command to this file as it was treated previously. Suggested-By: Quentin Schulz Reviewed-by: Quentin Schulz (From yocto-docs rev: 5b86879b3b5f3c51bc7fa5dd2848cf1153a22242) 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-08T13:36:38+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: a78d9bde7f90f860aa969b7d8e47350de9106183) Signed-off-by: Quentin Schulz Reviewed-by: Michael Opdenacker Signed-off-by: Richard Purdie

conf.py: add macro for Mitre CVE links

2023-05-26T16:32:51+00:00

Useful for CVEs that are not found (yet) on https://nvd.nist.gov/ (From yocto-docs rev: bd9add8a0e62465429cf62c314aaa766b7f6f544) Signed-off-by: Michael Opdenacker Signed-off-by: Richard Purdie