So that external users of the domain only interested in e.g. referencing
roles, can skip tweaks made to Breathe's directives.
Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
Add UI to select preferred search engine when Google Programmable Search is
enabled. The user's preference is saved using local storage.
This also makes the search input field of type "search" for better UX (in
particular on mobile).
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Add Google Programmable Search engine to the documentation, while
leaving it possible to easily revert to the built-in Sphinx search
engine. As the styling of the search results is apparently not thought
to be easy to tweak, the gcs.css stylesheet might require further
improvements.
Fixes#55173.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This picks up custom javscript from Godot documentation and uses CSS
rules we already had in place (only they were not used) to tweak the
page scroll behavior. As folks scroll down the page, the Zephyr logo in
the top right corner gradually disappears, leaving more room for the
navigation menu.
Also, when scrolling in the navigation pane, the UI there is slightly
adapted to make it more clear that the search box is "fixed", plus,
when one reaches the bottom of the navigation tree and continues
scrolling, the "main" page scrolls down.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Improve documentation about pytest integration with Twister. Add
examples of usage, improve description of available options and
introduce automatic doc generation of two plugin classes (DeviceAdapter
and Shell) basing on their docstrings from source code.
Signed-off-by: Piotr Golyzniak <piotr.golyzniak@nordicsemi.no>
This commit loads the RTD theme as a Sphinx extension, which has the
benefit of going through said extension's "setup" method, effectively
setting useful settings such as default permalink icon (moving away from
the default, not so pretty, "¶").
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The index at the end of the PDF document can contain pretty long strings
that don't fit in the default 2-column layout.
This commit makes the index use a single-column.
Note: this relies on LaTeX package idxlayout which should already be
included in the packages recommended for installation in our
instructions.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
- Add extension to get git metadata (date, SHA-1, ...) regarding the
latest update made to a page
- Add date of last "actual" update to each manually authored doc page
- Add admonition inviting to report issues
- Add button in breadcrumb to report issue
Fixes#60622.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Update the vcs_link extension to also support generating "edit" URL
vcs_link_version is also now a Sphinx config making its value available
to extensions.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Force code blocks with no 'language' explicitly set to render with no
highlighting. The current default was to use python (bad), and there
would also be an option to set it to "guess" but this doesn't work all
so well (ex. some C blocks would be detected as Transact-SQL!).
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Use Noto as baseline font and Inconsolata Nerd Font for source code.
These are both esthetically pleasing and have good Unicode coverage.
NOTE: Unsupported characters (i.e. emojis, at the time of this commit)
are rendered as tofu (i.e. a square).
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
XeLaTeX is a TeX typesetting engine that extends LaTeX with support for
Unicode and modern font technologies such as OpenType.
It is included in all the LaTeX distro recommended for Zephyr so it is
safe to assume it is available to the user interested in building the
PDF documentation locally
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Add required settings for telling the copybutton Sphinx extension to
ignore prompts when copying a code block.
Both bash prompt and Zephyr UART prompt are ignored.
Examples of the new behavior:
.. code-block:: console
$ echo "Hello World"
Hello World
The copied text will be: 'echo "Hello World"'.
.. code-block:: console
uart:~$ l2cap connect 29
Chan sec: 1
L2CAP connection pending
Channel 0x20000210 connected
Channel 0x20000210 status 1
uart:~$ l2cap send 3 14
Rem 2
Rem 1
Rem 0
Outgoing data channel 0x20000210 transmitted
Outgoing data channel 0x20000210 transmitted
Outgoing data channel 0x20000210 transmitted
The copied text will be: 'l2cap connect 29\nl2cap send 3 14'.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Generate index of west projects and information about them.
Based on an extension from sdk-nrf repo.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
rtd_theme 1.2.x is required when using Sphinx >= 6.0, otherwise certain
features like search are broken. Note that jQuery support needs to be
enabled manually now using `sphinxcontrib.jquery` extension. Also update
Sphinx to latest 6.x release, 6.2 as it contains some fixes.
Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
We make sure that we have the 'root' and 'xml' defined for the project
which is necessary at the moment for docleaf though the 'root' is only
really used for the 'linkcode' integration.
Signed-off-by: Michael Jones <m.pricejones@gmail.com>
This switches the Sphinx conf.py file over to using the
'docleaf.doxygen' module and the associated docleaf configuration
entries, replacing the breathe module and config.
Signed-off-by: Michael Jones <m.pricejones@gmail.com>
This reverts commit 4516117e9f.
A git bisect showed that the duration of an incremental build doubled
after this commit enabled `numfig=True`. Measurements shared and
discussed in #37572, #55708 and #56631 confirmed this. Here are yet more
measurements below in two different system configurations building docs
for very recent Zephyr commit b10817ba25 + all `:numref:` removed by
the previous commit. In other words these numbers show the cost of
`numfig=True` _without_ even using `:numref:`.
* Ubuntu 22, 8 cores
sphinx-build --version 4.3.2
numfig=True numfig=False
- from scratch 7 min 15 s 6 min 40 s
- one-line .rst change 48 s 24s
* Current Arch Linux, 72 cores
sphinx-build --version 6.2.1
numfig=True numfig=False
- from scratch 5 min 0 s 4 min 50 s
- one-line .rst change 37 s 18 s
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
Sometimes we want to force the inlining of a __syscall. Introduce a new
__syscall_always_inline symbol to do that.
Signed-off-by: Carlo Caione <ccaione@baylibre.com>
Document this new build system feature.
Since its purpose is customizing application builds, the logical place
for the main body of documentation is in a new snippets/ directory in
doc/build/. Create that directory and add its initial documentation.
Like boards and samples, however, we expect people to write
documentation for each snippet within the directory that defines the
snippet itself. Therefore, add a new top-level snippets/ directory and
stub out the documentation needed to document individual snippets as
well.
Add documentation and cross-references in other required places as
well.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Help search engines flag "latest" version of the documentation as
the canonical source by setting Sphinx's html_baseurl.
Fixes#54749.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Fixed the version selector so that it links to latest version of the LTS
release instead of 2.7.0.
Fixes#54786
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Added another custom role `module_file` which functions like
`zephyr_file` but for any module in the west manifest.
The new role must take a module as an argument. Example syntax:
```rst
:module_file:`module-name: path/within/module`
```
or with custom link text:
```rst
:module_file:`my link text <module-name: path/within/module>`
```
This change also moves the hardcoded project name and link to
github to `doc/conf.py` by adding the configuration values
`link_roles_manifest_project` and `link_roles_manifest_baseurl`
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
This patch adds support for the `linkcheck` Sphinx builder, so that we
can easily check for broken links in the documentation.
It can be run like this:
ninja linkcheck
Or, using the Makefile shim:
make linkcheck
All Zephyr Github issues links are ignored, since we have lots of these
URLs and they quickly hit GH rate limit. They have small chance to be
incorrect, so we should be ok.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The nitpicky mode warns about any broken reference. It is useful to keep
docs in good shape, however, there are some references that will never
be resolvable. Provide an initial list to decrease the number of
warnings that are not relevant/can't be fixed.
Note that the Sphinx nitpicky mode can be enabled by either setting
`nitpicky = True` in `doc/conf.py` or by setting the `-n` flag in
`SPHINXOPTS`.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Starting with Sphinx 6.0, extlinks caption with %s will be required.
Sphinx 5.x already warns about this requirements, so fix it.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The sphinx-copybutton extension adds a button to every code snippet
that, when clicked, copies the code to the clipboard.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
