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>
Upgrade to Doxygen version 1.9.1. Package is downloaded directly from
the Doxygen official site, since it is not yet part of the latest Ubuntu
LTS. Note that libclang1-9 and libclang-cpp9 are runtime dependencies
required by Doxygen.
NOTE: Documentation can still be built with older Doxygen versions (e.g.
1.8.17 shipped with latest Ubuntu LTS), however, the template used in
upcoming patches claims to work better with Doxygen 1.9.1 or 1.9.2.
Using 1.9.1 as theme v1.6.0 has some issues on mobile view when using
Doxygen 1.9.2, see
https://github.com/jothepro/doxygen-awesome-css/issues/47.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Use 0.11.1 to build the docs. The docstrings are the same as 0.11.1a1,
so it doesn't make a difference in the output, but let's keep things
clean now that the final release is up.
Fix typos in the release notes.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
With CMake minimum required as 3.20.0 we update CI to use docker image
v0.18.2, which contains CMake 3.20.5.
For doc builds we fetch the same CMake v3.20.5 but using pip as the doc
build doesn't use the docker image.
The main reason for increasing CMake version is better toolchain
support.
The decision to bump the CMake version was taken by the Toolchain WG.
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>
To get confirmation this will work before I cut the release. That
pre-release is already available on PyPI.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Artifacts will be required for the publish workflow, so do not let the
build workflow succeed without them being uploaded correctly.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Storing west version in a single place avoids keeping duplicates in each
job. Also added a note on why pinning version is important: west
docstrings are extracted from the installed version.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The pip cache should be discarded if any of the required dependencies
changes, so use the hash of the requirements file as a key source.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
xz compression reduces the html archive sice from ~350MB to ~90MB (at
the cost of more compression time). Compression has been moved to a
separate step.
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 means a light requirements-doc.txt is enough for doc writers. See
previous discussions in PR #31199 and PR #31239
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
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>
`check-warns` step is no longer used since the introduction of
`warnings_filter` extension.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This is mainly a feature release which includes a few ways to speed up
'west update', along with a couple of fixes and other changes.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Upgrade core Python dependencies (setuptools, wheel, pip) at a system
level. Some old versions of pip do not resolve the dependency chain
correctly, this is why it has been added to the list.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Documentation build still contained references to the old top Makefile
and old known-issues folder.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Some of the generated documentation depends on the devicetree scripts.
E.g. the bindings index uses edtlib.
We don't have a well-defined interface boundary here for managing
dependencies, so let's just add the entire dts directory to the
'paths' glob list in doc-build.yml. This will ensure we don't
accidentally change some DT implementation detail in a way that breaks
the docs.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Move the top-level Makefile to the documentation folder as it is only
used for documentation.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This should produce no changes in the docs since there are no API
changes in this point release, but let's just keep the build up to
date with the version being documented for cleanliness.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
As recommended by @mbolivar-nordic and... stackoverflow.
While I could not reproduce this locally, this should get rid of many
non-fatal pip errors in CI all looking like this one:
Building wheels for collected packages: PyYAML, progress, psutil, ...
Running setup.py bdist_wheel for PyYAML: started
Running setup.py bdist_wheel for PyYAML: finished with status 'error'
Complete output from command /usr/bin/python3 -u -c "import setuptools,
tokenize;__file__='/tmp/pip-build-b3sj5a6m/PyYAML/setup.py';
f=getattr(tokenize, 'open',open)(__file__);code=f.read().replace(
'\r\n', '\n');f.close();exec(compile(code, __file__, 'exec'))"
bdist_wheel -d /tmp/tmpvn0bt6xfpip-wheel- --python-tag cp36:
Failed building wheel for PyYAML
usage: -c [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
or: -c --help [cmd1 cmd2 ...]
or: -c --help-commands
or: -c cmd --help
error: invalid command 'bdist_wheel'
----------------------------------------
Running setup.py clean for PyYAML
Etc.
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
Use descriptive and unique job names, otherwise we end up with those
showing up in different location with no way to know which is which.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Github has deprecated add-path, so update the workflows that use it to
the new method of setting the PATH.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
Changing .known-issues/doc should always trigger a documentation build
so add it to the filters.
Signed-off-by: Fabio Utzig <fabio.utzig@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>
Inspect the hex file with intelhex, and fail if the hex file has any
contents in the UICR area(s).
family == 'NRF52' still always does --sectoranduicrerase, but this
option is not available on other families.
Add --force command line option to proceed with flashing instead of
failing.
Signed-off-by: Øyvind Rønningstad <oyvind.ronningstad@nordicsemi.no>
breathe v4.15.0 was just released and fixes some compatibility issues
with latest sphinx, the combo works, however with many warnings that we
still need to either fix or whitelist. This is temporary until we are
able to use those new versions.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Version 3.0.0 release recently break doc build, lock version of sphinx
to something compatible while we upgrade dependencies...
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
In some cases especially for on-going development & debugging of real
application it might be useful to load and run not from flash but
from RAM in that case there's one catch: we cannot reset the board
after loading memory with our app.
That's because:
a) RAM we use might be either cleared on reset or might enter
unpredictable state with portion of previously loaded data
being corrupted.
b) Reset vector most probably still point to ROM/flash and so
our current application won't be executed on reset.
So instead of "run reset" command of OpenOCD we'll use
"resume 0x12345678". Where 0x12345678 is our application's
entry-point (which BTW may very well not match beginning of
the .text section or link base).
Now to extract the entry-point we need our application's zephyr.elf
and since we already have a requirement for Elf we may use it for
loading because OpenOCD does it perfectly fine moreover automatically
detecting loaded image type (binary, hex, Elf etc).
And to use that nice feature just add "--use-elf" to west's
command-line for boards that use "openocd" runner. Like that:
----------->8--------------
west flash --use-elf
----------->8--------------
Signed-off-by: Alexey Brodkin <abrodkin@synopsys.com>
Make a few cleanups to the doc build action:
1. Only do action for pull requests - action is meant to test PRs
2. Remove west update / cache of modules as we dont need them for docs
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
GitHub checks need to be uniquely named, and 'Documentation' conflicts
with the ci-tool name. Rename this while we are running both so the
names don't conflict.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
This github workflow will build the html docs on a pull request or push.
This is similar to the current ci-tools 'Documentation' check. One
difference is this version produces a GH artifact of the html docs
instead of posting it to S3. The artifact is a tarball that is than
zip'd (not gzip).
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
