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