This allows us to identify any patterns that we can remove or that
we didn't realise are no longer in use. This might happen if issues
within doxygen or docleaf are resolved.
This allows us to remove the pattern:
.*Duplicate C declaration.*\n.*'\.\. c:.*:: uint16_t id'.*
which does not match anything in the current set up.
We also split the filter patterns in known-warnings out into different
sections depending on their cause.
Also extend the pattern parser to ignore empty lines so that we can
have some formatting in the known-warnings file.
Signed-off-by: Michael Jones <m.pricejones@gmail.com>
There are times when the log message is an exception object and that
causes the regex to fail with a TypeError. Here we work around that
by converting the input to a string.
Signed-off-by: Michael Jones <m.pricejones@gmail.com>
Instead of breathe.
I'm not sure of the best version comparison to use. There is no
intention to break the API for docleaf but it is also still young
in some ways and there might be adjustments to the configuration values
that would need to be reflected in the version number as it is still
pre-1.0 that would only be a minor version change.
Signed-off-by: Michael Jones <m.pricejones@gmail.com>
Restore appearance of kconfig search, with rounded corners and
black background. This should resolve visibility issues encountered
on some browsers when running in dark mode
Fixes#53568
Signed-off-by: Daniel DeGrasse <daniel.degrasse@nxp.com>
This patch allows copying a URL to the current Kconfig search results.
For example, I can now share the search results for "CONFIG_TEST.*". A
new button is added to the search box that, when clicked, copies to the
clipboard the URL.
This feature is achieved by prepending query hashes with '!'. When '!'
is found, the content of the URL hash is left intact, whereas before it
was always enclosed within '^$' to produce an exact match.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
If two modules started with the same prefix, e.g. nrf and nrfxlib, the
file name prefix was incorrectly set with the common prefix. Include
trailing "/" to the comparison, so that we match the full module name.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Added another custom role `module_file` which functions like
`zephyr_file` but for any module in the west manifest.
The new role must take a module as an argument. Example syntax:
```rst
:module_file:`module-name: path/within/module`
```
or with custom link text:
```rst
:module_file:`my link text <module-name: path/within/module>`
```
This change also moves the hardcoded project name and link to
github to `doc/conf.py` by adding the configuration values
`link_roles_manifest_project` and `link_roles_manifest_baseurl`
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
When searching for a certain group of Kconfig options, e.g. CONFIG_BT*
it may be useful to view more than 10 options at the same time. This
patch adds a new combo box that allows to increase the number of results
per page (10, 25 or 50).
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This patch modifies the Kconfig search _algorithm_ so that it aligns
with how menuconfig search works:
- Input is splitted into multiple search terms (space based split)
- Both Kconfig option name and prompt are used
- Regex search is used instead of match, it is less efficient but will
search the whole string, leading to more results.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Sort database entries so that search results appear in alphabetical
order based on the given input. This mimics the behavior of menuconfig
search functionality.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The boards command was not properly using the zephyr_module
functionality to obtain the board roots of all modules. Fix that by
moving the functionality required to the core zephyr_module file and
reuse it from external scripts.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Promptless choices can show up as parents when, e.g., people define
choices in multiple locations, including modules. Render them using the
built-in Kconfig expression to string formatter, so that they show up as
'<choice (...)>'.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Render the menu path where an option can be found. For example,
CONFIG_SPI: (Top) > Device Drivers.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This patch adds support for displaying the "selected by" and "implied
by" entries in the Kconfig search extension, ie, reverse dependencies.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
When using `zephyr-app-command` the CMake arguments and values are not
having spaces between them, except the `-B build`.
Remove the space, so that `-B build` becomes `-Bbuild` and thus looks
similar to other `-<arg><value>` occurences.
Example before this commit:
> Use cmake to configure a Ninja-based buildsystem:
> cmake -B build -GNinja -DBOARD=reel_board samples/hello_world
>
> Now run ninja on the generated build system:
> ninja -C build
With this commit:
> Use cmake to configure a Ninja-based buildsystem:
> cmake -Bbuild -GNinja -DBOARD=reel_board samples/hello_world
>
> Now run ninja on the generated build system:
> ninja -Cbuild
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
Add a new extension to handle Kconfig documentation. This means that no
more CMake hackery is required. However, the way it works differs from
the current approach. Instead of creating a single page for each Kconfig
option, the extension creates a JSON "database" which is then used on
the client side to render Kconfig options on a search page. The reason
to go for a single page choice is because Sphinx is significantly slow
when handling a lot of pages. Kconfig was responsible for an increase of
about ~10K pages.
Main features:
- Generates a Kconfig JSON database using kconfiglib APIs.
- Adds a new Sphinx domain for Kconfig. The domain provides a directive,
:kconfig:search:: that can be used to insert a Kconfig search box onto
any page. This page is where all Kconfig references inserted using the
:kconfig:option: role will point to. The search functionality is
implemented on the client side using Javascript. If the URL contains a
hash with a Kconfig option (e.g. #CONFIG_SPI) it will load it.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
After the introduction of #41688, doxyrunner extension modifies the
fmt_vars content (from a variable defined in `conf.py`) when the output
directory variable is defined. This means that Sphinx will always get an
outdated environment and so will always perform a full build instead of
an incremental build. This patch makes a copy first to prevent this
situation.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The doxyrunner_outdir_var option allows to specify which variable (if
any) is used to represent the output directory (as used by
OUTPUT_DIRECTORY). This makes sure that other options referencing it are
processed correctly, since the output directory is not passed as a
variable.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Redirect stderr to DEVNULL when running `git describe --exact-match`.
This prevents messages like "fatal: No names found, cannot describe
anything." to be shown.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The vcs_link should only run for the HTML builder, since it is the only
target of this extension. The other builders do not have the templates
instance, making them fail.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Add vcs_link extension. The extension can be used to obtain VCS (Git)
URLs for given Sphinx documents.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The setup() method is trying to find the zephyr repository by name,
but it's not passing allow_paths=False to the west method it uses to
search.
That may lead to unpredictable results depending on what the current
working directory is in the calling environment.
For robustness, disallow paths and make sure we are only searching for
the zephyr project by name.
Add some more comments to explain what is going on and clean up the
empty string handling while we're here.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
The extension was not evaluating the GENERATE_HTML option correctly. The
get_doxygen_option returns a `List[str]`, not a `str`.
This effectively means that the Zephyr apidoc has not been updated for a
while as the extension was not moving the output to the final
destination folder.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
QUIET flag is now overriden according to the `doxyrunner_silent`
configuration value.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This change will process Doxygen output and will map it to the Sphinx
logger. Things like errors and warnings will be mapped to actual Sphinx
logger error and warnings. In practice this means that when Doxygen
throws a warning and Sphinx is run in "-W" (warning as error) mode, the
build will fail. It also has some other advantages such as the
possibility of filtering issues using the warnings_filter extension.
It is also expected that CI errors not being displayed issue is fixed
with this change.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
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>
Add a new extension to support the :kconfig: role and .. kconfig::
directive. This removes the need of using :option:.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Sphinx provides a way to persist data across builds: the
BuildEnvironment. The build environment is automatically managed by
Sphinx, so there is no need to take care of loading/dumping cache files.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Use file hashes instead of paths and modification times. This method is
fits better on systems using cache mechanisms. Note that hash is
computed using content obtained in UTF-8 text mode for portability
reasons.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Path.rename() uses os.rename() internally. Per the Python docs:
The operation may fail on some Unix flavors if src and dst are on
different filesystems.
Since 'src_adjusted' is in a temporary directory, on my flavor of
Unix, that's in /tmp, which is indeed on a different filesystem than
'dst', a destination in the doc build directory on my root filesystem.
This is causing the following error when I build the docs:
Handler <function sync_contents at 0x7f9b8fca9c10> for event
'builder-inited' threw an exception (exception: [Errno 18] Invalid
cross-device link: '/tmp/tmpfscfo20o/index.rst' ->
'/home/mbolivar/zp/zephyr/doc/_build/src/reference/drivers/index.rst')
Fix this by using shutil.move() instead of Path.rename(). The shutil
function handles cross-filesystem moves correctly. It did not take a
path-like object for both its src and dst arguments until Python 3.9,
though, so we need to convert to strings for portability on earlier
but still supported versions.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
When including other rst files (via .. include::) the existence of the
included file may depend on when the _adjust routine is called, so only
ignore absolute paths.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
PosixPath or WindowsPaths are not portable, so using them on pickle
files, which can potentially be re-used is not safe. Changed to use the
posix path as a string.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This needs to use 'main' for its default now.
Without this patch, GitHub redirects to main, but displays a banner
that says 'Branch not found, redirected to default branch' at the top.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Make HTML output optional. The extension checks the `GENERATE_HTML`
option to check if active.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
zephyr.doxyrunner Sphinx extension is meant to replace multiple Python
and CMake scripts into a single Sphinx extension.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Explicitely mention that these files are intentionally empty. These
changes should make compliance checks pass.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
