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>
Sphinx supports parallelized build (-j) option. Setting it to `auto`
makes use of all available cores. This option seems to speed up the
build significantly on multi-core machines.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Fixes: #31486
Sourcing `cmake/extensions.cmake` to have Zephyr functions available
when including Zephyr CMake files into doc build system.
This is a follow up on #30904 by supporting generated Kconfig files
that might contain lines as `osource "$(ZEPHYR_<MODULE_NAME>_KCONFIG)"`
to be properly parsed for doc building.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Fix documentation build issue where generating the kconfig rST was
failing due to missing Kconfig.shield* files. Add an extra step in
CMakeLists.txt to properly generate them, similarly to what is already
done for Kconfig.soc*.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
Add generated documentation content for known devicetree bindings
using the Binding abstraction which was just added to edtlib. This
works similarly to the way Kconfig content is generated, so extract a
bit of common helper code for doing that out and rename the relevant
files to keep the distinction clear.
Make the documentation build system respect a preset DTS_ROOT. In this
way, out of tree bindings can be added to the generated content by
telling the documentation build system where to find them, identically
to how out of tree bindings can be added to a Zephyr application.
Similarly, make the output directory configurable.
Fixes: #28865
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Rather than doing a doc build on every PR, limit it to PRs that either
touch a file in doc/, *.rst and what's listed as DOXY_SOURCES in
doc/CMakeLists.txt.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Fixes commit 15fbf707ca ("doc: revert to copy files with
extract_content.py directly") that removed (2 years ago!) the definition
of EXTRACT_CONTENT_OUTPUTS while leaving it in use by sphinx-html and
sphinx-latex.
On my Linux box "make sphinx-html" is more than 5 times faster than
"htmldocs", likely because it does not build doxygen nor kconfig.
Also add missing WORKING_DIRECTORY for consistency with regular
targets and to fix this error:
Exception occurred:
File "~/.local/lib/python3.8/site-packages/sphinx/
search/__init__.py", line 284, in __init__
with open(scoring, 'rb') as fp:
FileNotFoundError: [Errno 2] No such file or directory: 'scorer.js'
I don't know when that second regression appeared.
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
This commit introduces support for multiple SOC_ROOT.
This means that additional SOC_ROOTs specified using -DSOC_ROOT as
argument to CMake will be forming a list together with ${ZEPHYR_BASE}.
This allows for greater flexibility, as developers can now specify
multiple out-of-tree SoCs and not worry about the SoC used for the
board they compile for.
Also it avoid code, such as:
if(BOARD STREQUAL my_board_using_out_of_tree_soc)
set(SOC_ROOT some/out/of/tree/soc/path)
endif()
in application CMakeLists.txt.
Finally, allowing multiple SOC_ROOTs prepares for specifying SOC_ROOTs
in Zephyr modules.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
This provides a better error message when building with CMake and
forgetting ZEPHYR_BASE or not registering Zephyr in the CMake package
registry. See parent commit for more details (split from parent for
better readability).
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
