The hw feature generation takes a long time. The HW_FEATURES_TURBO_MODE
option completely disables hw feature generation. Add a new option
HW_FEATURES_VENDOR_FILTER to be able to selectively enable hw feature
generation only for a given list of vendors. This option is useful
when working on board documentation pages.
Signed-off-by: Aksel Skauge Mellbye <aksel.mellbye@silabs.com>
OUTPUT_DIR was not passed to the html-live target, causing a
Python exception:
```
TypeError: argument should be a str or an os.PathLike object
where __fspath__ returns a str, not 'NoneType'
```
Signed-off-by: Aksel Skauge Mellbye <aksel.mellbye@silabs.com>
Add a new hardware features filter to the board catalog that allows
users to filter boards based on their supported hardware capabilities.
The features are extracted from the devicetree files and organized by
binding type.
Key changes:
- Extract hardware feature descriptions from devicetree bindings
- Add HW_FEATURES_TURBO_MODE option to skip feature generation for
faster builds (similar to DT_TURBO_MODE)
- Add tag-based UI for filtering boards by hardware features
The feature can be disabled for faster documentation builds using
-DHW_FEATURES_TURBO_MODE=1 or by using 'make html-fast'.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Pull the output build folder from the environment, instead of hardcoding
the HTML output folder, which is wrong for the latex build.
Signed-off-by: Jordan Yates <jordan@embeint.com>
Add two new commands that automatically locally host the generated
documentation upon completion and rebuild/rehost when the input files
change without any user interaction.
For more info see: https://pypi.org/project/sphinx-autobuild/
Signed-off-by: Jordan Yates <jordan@embeint.com>
Get the output directory from environment variables instead of
attempting to reparse the CLI arguments, as these can actually refer
to a program other than `sphinx-build` (for example `sphinx-autobuild`).
Signed-off-by: Jordan Yates <jordan@embeint.com>
This allows specifying the environment variable
ZEPHYR_DOXYGEN_OVERLAY pointing to a overlay file for
doxygen to override configs in the base zephyr.doxyfile.in
for local document builds.
Signed-off-by: Daniel Leung <daniel.leung@intel.com>
Our documentation uses image formats such as WebP that are not supported
by LaTeX. This commit enables Sphinx's sphinx.ext.imageconverter
extension, and updates the documentation to indicate ImageMagick is
required to build docs.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
When something goes wrong in Sphinx or extensions, we'll get a detailed
traceback, so we can easily debug issues in CI.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add a new CMake option to append options to SPHINXOPTS. This allows us
to easily extend default SPHINXOPTS. This patch also restores the "-j
auto" option in CI (now that we use a custom runner).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Run Sphinx in warnings as error mode, but keep going so that all issues
are reported to the user.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
If west is installed, we have to build the Zephyr documentation with a
recent version of west. This is because the west API documentation is
part of the Zephyr documentation, and the west API documentation
contains Sphinx autodoc directives which pull API documentation out of
the west source code itself. This is similar to how we pull Doxygen
comments out of the Zephyr API headers using breathe. (If west is not
installed, we don't build the west API docs, so you can uninstall west
if you don't want this.)
The current API docs require west v1.0.0 or later to build, since that
version of west introduced new APIs and documentation for them not
available in prior versions.
Signed-off-by: Martí Bolívar <marti.bolivar@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>
Re-add the SEP setting in the documentation CMakeLists. This was dropped
in:
fc942ef7d3 doc: use new kconfig extension
And currently prevents building the documentation locally if a
PYTHONPATH is set.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
Creating a doc.cmake to the new Zephyr CMake modules dir.
This removes the need for `set(NO_BOILERPLATE TRUE)` before loading the
Zephyr CMake package.
It also removes the need within the doc/CMakeLists.txt file to manually
include individual parts of the Zephyr CMake files as this is now
controlled through a single Zephyr CMake doc module.
This aligns the way a Zephyr package is sourced with other places.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Similar to Kconfig turbo mode, add a Devicetree bindings turbo mode. In
this mode, the Devicetree bindings pages are not generated. Instead, a
page with dummy symbols is created. This takes ~1K pages out of the
build, resulting in faster builds. This mode can be useful while in
development or CI PRs.
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>
Support for ARM Compiler C library.
This commit add support for the ARM Compiler C libary in:
- Kconfig
- libc/armstdc
A new Kconfig symbol is added to allow a toolchain to specify if they
support linking with the minimal C library.
Also the CMake variable `TOOLCHAIN_HAS_NEWLIB` is exported to Kconfig
so that CONFIG_NEWLIB_LIBS can only be enabled if the toolchain has
newlib.
The armclang toolchain selects the CMake scatter file generator and
disables support for the LD linker template which is not supported by
armlink.
For the ARM Compiler C library, a corresponding lib/libc/armstc/ folder
with a minimal implementation to work with the ARM Compiler C library
is added.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Move to CMake 3.20.0.
At the Toolchain WG it was decided to move to CMake 3.20.0.
The main reason for increasing CMake version is better toolchain
support.
Better toolchain support is added in the following CMake versions:
- armclang, CMake 3.15
- Intel oneAPI, CMake 3.20
- IAR, CMake 3.15 and 3.20
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@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>
The LaTeX build succeeds without the fix_tex.py script, so remove it.
The file actually mentions ".tex file produced by doxygen", so it may
not be relevant for Sphinx after all.
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>
This is useful if the user wants to set specific latexmk options, e.g.
-quiet for CI.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Sphinx automatically generates a Makefile/make.bat that allows to build
the LaTeX output. This converts the CMake `pdf` target into a shim to
this Makefile, making the solution more future-proof if Sphinx decides
to change something.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Indicate which files have to be cleaned for each target. This feature is
only supported for CMake >= 3.15 and is ignored on older CMake versions.
Build will still succeed, but the `clean` target will not clean the
additional build files.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Simplify the devicetree generation. Most of the extra options are not
used, so they have been removed to make things easier to maintain.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Refactor the Kconfig target. Mostly formatting in this case. The Kconfig
script is also added as a dependency of the CMake configuration step, so
that if it is changed, the Kconfig generation step will be re-run.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Refactor the pdf build targets. The Sphinx latex build is now invoked by
the 'latex' target. The 'pdf' target can be used to build the resulting
LaTeX files.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Refactor HTML targets. The 'html' target is kept as is, 'sphinx-html'
equivalent is now 'html-nodeps'.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Group dependencies all together. Some have been simplified, e.g. Sphinx
and others improved, e.g. LaTeX.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
west is currently optional, however, when not found its docs will not be
available and the zephyr_module CMake utility will not be able to find
modules (unless ZEPHYR_MODULES is used). Other Python dependencies, i.e.
the ones listed in the requirements file, are not checked, so do the
same for west.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Always source the Zephyr base soc and shield (board root) Kconfigs
directly from Kconfig instead of generated Kconfig files.
This has the benefit that it is no longer necessary to generate Kconfig
files to source SoC root and shield (board root) when no custom roots
are provided.
Also this cleans up the doc/CMakeLists.txt and ensures that the
doc/CMakeLists.txt is not getting out of sync with the Kconfig.cmake.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
The usage of -W may lead to the loss of the Sphinx build environment
even for small typos. Remove this option from the defaults but still
enable it on CI, where the fail-fast behavior given by -W is desired.
Fixes#36033
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Make default Sphinx options more user-friendly, i.e. colored output so
that one can easily follow build progress.
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>
Replace the restore modification times with a new script that is more
specific to the Doxygen+Sphinx needs.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
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>
We are now in the process of extracting edtlib and dtlib into a
standalone source code library that we intend to share with other
projects.
Links related to the work making this standalone:
https://pypi.org/project/devicetree/https://python-devicetree.readthedocs.io/en/latest/https://github.com/zephyrproject-rtos/python-devicetree
This standalone repo includes the same features as what we have in
Zephyr, but in its own 'devicetree' python package with PyPI
integration, etc.
To avoid making this a hard fork, move the code that's being made
standalone around in Zephyr into a new scripts/dts/python-devicetree
subdirectory, and handle the package and sys.path changes in the
various places in the tree that use it.
From now on, it will be possible to update the standalone repository
by just recursively copying scripts/dts/python-devicetree's contents
into it and committing the results.
This is an interim step; do NOT 'pip install devicetree' yet.
The code in the zephyr repository is still the canonical location.
(In the long term, people will get the devicetree package from PyPI
just like they do the 'yaml' package today, but that won't happen for
the foreseeable future.)
This commit is purely intended to avoid a hard fork for the standalone
code, and no functional changes besides the package structure and
location of the code itself are expected.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
