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>
The filtered warnings are warnings we can't fix due to Sphinx
limitations, so showing them just adds noise to the doc build process.
The extension already defaults to silent mode.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
References should be maded using the appropriate role, e.g. :ref:,
:c:func:, :kconfig:, etc.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add a new toctree with reference material, including:
- API docs (Doxygen)
- Kconfig options
- Devicetree bindings
Note that the toctree is rendered manually due to the limitations Sphinx
has when it comes to including relative URLs. Hardcoding absolute URLs
in toctrees is possible, but that means we'd need to update the toctree
on every release (to point to /version/ URL), and downstream users of
the documentation would have to manually patch the toctree with their
own URL. In order to make local builds work, version prefix is only
added if publish tag is provided.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Enable the vcs_link extension so that pages contain "Open on Github"
link at the top.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Enable figures enumeration. This option allows to use :numref: in order
to reference figures, thus allowing more precise references other than
"the figure below" or similar.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Drop the 2.2.0 version entry so that its link is removed from the docs
drop-down list.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add 2.7.0 to the version list so that a link to it is created on the
documentation drop-down list.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Render Zephyr version in both, standalone Doxygen build and Sphinx
controlled build. In standalone mode, the package version given by
find_package(Zephyr...) is used, while in Sphinx build the conf.py
version is used.
The project brief has been shortened to make project title more compact
while still containing relevant information.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This patch improves the general look and feel of the LaTeX (PDF)
documentation build. Changes include:
- A custom title with relevant information has been created
- Some colors have been adjusted to match those in the web template
- Charter font family is used
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
ZEPHYR_BASE and ZEPHYR_BUILD directories were passed to Sphinx via
environment variables. However, these paths can be easily discovered by
the conf.py file itself. As a result, Sphinx is less dependent on CMake
to operate.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Enable the built-in Sphinx Graphviz extension to allow creating Graphviz
diagrams natively on the source files. Some style defaults have been
enabled to make sure diagrams are consistent and have good quality in
both light and dark modes.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Benjamin Cabé
Anas Nashif
Andrei Emeltchenko
Gerard Marull-Paretas
Michael Jones
Marc Herbert
Carlo Caione
Marti Bolivar
Stephanos Ioannidis
Gaute Svanes Lunde
Fabio Baltieri
Gerard Marull-Paretas
Dan Kalowsky
Christopher Friedt