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>
Most of the content in the default index is HTML only, so create an
index just for PDF and keep it clean.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
The eager_only is currently breaking the usage of the `.. only``
directive, so remove it. Documentation seems to build fine without it,
so it has been removed for now.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
the `doc-examples` project is not used and, in fact, is a duplicate of
the Zephyr project.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Sphinx handling of 404 page is not that easy when using theme
customizations. Enabled the `sphinx-notfound-page` extension (maintained
by readthedocs) to fix its displaying.
Also adjusted Zephyr logo (was causing some Sphinx processing errors
when trying to scale it).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The scrolling customizations were used to hide the logo when scrolling
down. With this change, logo is always displayed.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Since logo already brings to home page, remove the link displayed above.
It saves some vertical pixels while making docs nicer. Also adjusted
wy-menu-vertical max-height to account for the new height (note: was
wrong before).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Enable the :members: option by default when using breathe directives.
This exposes automatically stuff like structure fields.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
When this option is enabled some data structures have missing pages. Use
the default setting (NO).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
doxyrunner plugin replaces a series of CMake+Python hacks. These include
input changes tracking and incremental build output simulation.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Since Pygments 2.7.0 devicetree syntax is supported, so there is no need
to use a custom lexer. Version 2.9.0 introduces a fix that is required
for some devicetree snippets.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
A new look and feel for the Zephyr documentation. It is largerly based
on the work done by Godot Engine docs, but with some Zephyr specific
customizations.
Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
This function always returns the same value for a given thread.
Add the const attribute to it so the compiler won't call it over and
over needlessly each time _current is referenced, making for far more
efficient code.
The __attribute_const__ symbol is used to mimic the Linux equivalent.
We want to make it clear that this is distinct from the const keyword.
Fix the test_x86_cpu_scrubs_regs where the compiler wasn't told that a
bunch of registers are being clobbered as highlighted by this change.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
Replace current filter setup with the warnings_filter Sphinx extension.
Note that current regexes have been simplified to make them more
readable while keeping the most relevant information.
Sphinx warnings are now treated as errors (-W).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Format the configuration file so that it is more consistent (e.g.
uniform usage of single/double quotes).
Some minor cleanup performed too: removed some comments and a default
setting.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Switch to pathlib to make configuration more readable. sys.exit has been
replaced with an exception so that in case of failure error is displayed
(error details were hidden).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Organize configuration sections per group (project, general, HTML,
plugin options...).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
It is easy to have out-of-date comments since Sphinx settings evolve
(defaults, behavior...). A reference to the official documentation is
provided at the top of the file instead.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
manpage, texinfo and htmlhelp builders are not used, so remove their
settings as they are redundant.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Remove options that are commented out from conf.py. It improves
readability of the file.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Move static content to _static. It is better to prefix all Sphinx
related folders with an underscore to emphasize that the folder does not
contain actual documentation. Static content gets copied into _static
folder when documentation is built, so it also makes things more
consistent.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This allows RST documentation to do something like this:
See :dtcompatible:`vnd,foo` for more information.
This is transformed into a link to documentation for the "vnd,foo"
compatible.
Some devicetree compatibles may be handled by multiple bindings.
This can happen when the binding file is bus-dependent. Therefore, to
make this work, we need to change the way gen_devicetree_rest.py works
to ensure we have a good source of information for this compatible
regardless of how many bindings are associated with as follows:
- When only a single binding is associated with a compatible, the
:dtcompatible: link goes directly to the per-binding HTML page.
- When multiple bindings are associated with a compatible, this goes
to a new generated "disambiguation" page which links to all the
per-binding pages.
To avoid clashes, we stick the disambiguation pages into a
compatibles/ subdirectory of the generated bindings index root
directory.
Also reorganize the generated bindings output directory into
.../bindings/subdir/binding.rst files. For example,
dts/bindings/arm/arm,dtcm.yaml now gets its generated content in
.../bindings/arm/arm,dtcm.rst.
This brings the 'category' of binding (like 'sensor', 'i2c', etc.)
into the URL, which is a useful hint.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Rename the 'basics' page to basics.rst, adding a redirect for the old
title.
Rearrange some other index pages to improve the flow:
- Put relatively stale content in moving-to-west.rst to the bottom. I
expect pepole have either moved west or are choosing not to.
- Promote the release notes page higher up, since that seems more
important.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
The debugging section was generalized for flash and debugging tools.
The links were refactored accordly and all references were updated.
To be consistent, the directory doc/guides/debbugging was renamed to
doc/guides/flash_debug.
Signed-off-by: Gerson Fernando Budke <nandojve@gmail.com>
Breathe>=4.23.0 brings in basic xrefitem rendering support and fixes
issues parsing anonymous struct/unions. This version also adds a config
knob for showing or hiding enumerator values, so set it to generate
documentation compatible with previous versions.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
Enable Breathe SEPARATE_MEMBER_PAGES compatibilty; this option allows
resolution of a huge amount of references that are currently broken
(around 650 based on my grep foo!) due to issues in the Doxygen XML
generation when this option is enabled.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
Add __subsystem to list of attributes for the parser, and make the c
parser accept the same attributes than the cpp parser, after the change
to use the c parser for ".c" files.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
Older Breathe versions didn't work correctly with the C domain, so there
was a mismatch when refering to functions and #defines, using :cpp: or
:c: depending on the origin of the refered symbol. With Breathe >=4.19
the C domain works correctly so all symbols can be refered to with the
:c: role.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
Update methods used to include JS/CSS files, avoiding deprecated
versions the don't work on Sphinx>=3.x. The new methods work on both
Sphinx==3.x and Sphinx>=2.4.x.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
Fix the board redirects. The following boards existed before we moved to
a new style of URL for boards, and thus each have 2 entries (old style
old name to old style new name; new style old name to new style
new name):
- nrf51_pca10028
- nrf52810_pca10040
- nrf52840_pca10056
- nrf52840_pca10059
- nrf52_pca10040
- nrf52_pca20020
The following boards did not exist (or were not referenced) before we
moved to the new style of URL for boards, and thus only have one entry
(new style old name to new style new name):
- nrf51_pca10031
- nrf52811_pca10056
- nrf52833_pca10100
- nrf52840_pca10090
- nrf5340_dk_nrf5340
- nrf9160_pca10090
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
We are renaming the nrf5340 DK documentation page, and due to
re-organizing the doc directory we need to allow redirecting
the old URLs for nrf5340 DK board targets' documentation.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
The board name for the Thingy:52, so far known as nrf52_pca20020, is
renamed to thingy52_nrf52832. Its documentation and all references to
its name in the tree are updated accordingly. Overlay and configuration
files specific to this board are also renamed, to match the new board
name.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The board name for the nRF52840 Dongle, so far known as
nrf52840_pca10059, is renamed to nrf52840dongle_nrf52840. Its
documentation and all references to its name in the tree are updated
accordingly. Overlay and configuration files specific to this board are
also renamed, to match the new board name.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The board target for emulation of nRF52810 on nRF5DK, so far
known as nrf52810_pca10040, is renamed to nrf52dk_nrf52810.
Its documentation and all references to its name in the tree are
updated accordingly. Overlay and configuration files specific to
this board are also renamed, to match the new board name.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
The board name for the nRF52 DK, so far known as nrf52_pca10040, is
renamed to nrf52dk_nrf52832. Its documentation and all references
to its name in the tree are updated accordingly. Overlay and
configuration files specific to this board are also renamed, to
match the new board name.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
We are renaming the nrf9160 DK documentation page, and due to
re-organizing the doc directory we need to allow redirecting
the old URLs for nrf916 DK board targets' documentation.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
The nRF52840 DK board target, so far known as nrf52840_pca10056,
is renamed to nrf52840dk_nrf52840.
Its documentation and all references to its name in the tree are
updated accordingly. Overlay and configuration files specific to
this board are also renamed, to match the new board name.
Signed-off-by: Andrzej Głąbek <andrzej.glabek@nordicsemi.no>
We rename the nRF51 Dev Kit board target (nrf51_pca10028)
to nrf51dk_nrf51422. We update all associated references
in the supportive documentation and all nRF51-related
cofigurations and overlay files in the samples and tests
in the tree.
Signed-off-by: Ioannis Glaropoulos <Ioannis.Glaropoulos@nordicsemi.no>
Add 2.2.0 to the version pick list. Also remove old versions so that
the oldest one is the LTS release.
Signed-off-by: Johan Hedberg <johan.hedberg@intel.com>
The SoC, driver, and board support for the CC2650 and CC2650 Sensortag
aren't currently supported and we are removing them as such. If anyone
is interesting in supporting this platform we can easily recovery it
from git.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
All docs are treated equally in the search results. The built-in search
system knows to emphasize hits in titles and object names, but could use
some help understating hits in non-definitive docs. In particular, hits
to docs in the /boards, /samples, and /reference/kconfig docs are often
not as important as hits in other docs, so let's push them later in the
search result output.
We can tweak the search results scoring (and thereby the order of
display) via the ``html_search_scorer`` setting in ``conf.py`` along
with a piece of JavaScript to adjust the result score.
Fixes: #16935
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
