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>
There is no code to handle __syscall_inline so it is better removing
it from doxygen and checkpatch.
Signed-off-by: Flavio Ceolin <flavio.ceolin@intel.com>
As presented to the TSC, Zephyr's out-of-box experience for new
developers is, well, complicated. A number of suggestions were
presented including simplifying the getting started material to present
a straight-forward path through the setup and installation steps through
to getting a sample application built, flashed, and running.
This PR is a work-in-progress towards addressing this OOB experience
with a minimal-distractions version of the GSG. Alternatives, warnings,
and material that could lead the developer astray were moved to
alternative/advanced instruction documents (based on the previous
separate Linux/macOS/Windows setup guides) and a new "Beyond the GSG"
document.
We do take advantage of a sphinx-tabs extension for synchronized tabs to
present OS-specific instructions: clicking on one tab will display all
same-named tabs throughout the doc.
We hope (and will continue evaluating) that this new GSG gets developers
set up quickly and then we can send them along to other documents to
continue learning about Zephyr and trying other sample apps.
Thanks for all your previous feedback that I've worked
into this new version.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The mimxrt10{20,60,64}_evk board docs were renamed from <board>.rst to
index.rst in commit 0e4ff809d7 but were
missing entries in the html redirect list. Add them.
An entry for mimxrt1015_evk is not added because this board always had
an index.rst board doc.
Signed-off-by: Maureen Helm <maureen.helm@nxp.com>
The board area was renamed from riscv32 to riscv back in July to
accommodate riscv64 support. Fix the remaining references in
documentation.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Update conf.py to add the v1.14.1 release docs to the master docs
version pick list, and remove the original v1.14.0.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
dtlib.py and guiconfig.py do some hackery to build token and image
variable names, which triggers spurious pylint warnings like
scripts/dts/dtlib.py:243:28: E0602: Undefined variable '_T_LABEL'
(undefined-variable)
Suppress the warning for those files. The generated names get used in
lots of places.
Also suppress some warnings in doc/conf.py ('tags' is from Sphinx), and
fix a legitimate issue in scripts/dts/testdtlib.py.
This pylint check is useful enough to want enabled in the upcoming CI
check.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
A bare 'except:' can do some annoying stuff like eat Ctrl-C (because it
catches KeyboardInterrupt). Better to use 'except Exception:' as a
catch-all.
Even better might be to catch some more specific exception, because even
'except Exception:' eats stuff like misspelled identifiers.
Fixes this pylint warning:
doc/conf.py:99:0: W0702: No exception type(s) specified
(bare-except)
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Reported by pylint's 'bad-whitespace' warning.
Not gonna enable this warning in the CI check, because it flags stuff
like deliberately aligning assignments and gets too cultish. Just a
cleanup pass.
For whatever reason, the common convention in Python is to skip spaces
around '=' when passing keyword arguments and giving default arguments:
f(x=3, y=4)
def f(x, y=8):
...
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
The Next/Previous chapter buttons have been confusing in the past and
recent DX studies still show that folks read these as the "Next"
document to read in some defined order. These buttons are simply
another way to navigate through the document tree to the "Next" doc in
the table of contents. Let's remove these buttons (again).
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
The main change is the elimination of the bootstrapper, a design flaw
/ misfeature.
Update the documentation to be compatible with the 0.6.x releases as
well. This has to be done atomically, as there were incompatible
changes. Make use of the versionchanged and versionadded directives
to begin keeping track of how these APIs are evolving.
(Note that west 0.6.0 will remain compatible with the extension
commands in Zephyr v1.14 LTS as long as that is still alive. This
change is targeted towards Zephyr 2.0 users.)
This requires a bump in the shippable container and allows us to
simplify the west_commands test procedure.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
With the upcoming riscv64 support, it is best to use "riscv" as the
subdirectory name and common symbols as riscv32 and riscv64 support
code is almost identical. Then later decide whether 32-bit or 64-bit
compilation is wanted.
Redirects for the web documentation are also included.
Then zephyrbot complained about this:
"
New files added that are not covered in CODEOWNERS:
dts/riscv/microsemi-miv.dtsi
dts/riscv/riscv32-fe310.dtsi
Please add one or more entries in the CODEOWNERS file to cover
those files
"
So I assigned them to those who created them. Feel free to readjust
as necessary.
Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
This board and SoC was discontinued some time ago and is currently not
maintained in the zephyr tree.
Remove all associated configurations and variants from the tree.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
