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>
Gerard Marull-Paretas
Anas Nashif
Kumar Gala
Gerard Marull-Paretas
Nicolas Pitre
Martí Bolívar
Mikkel Jakobsen
Gerson Fernando Budke