When building the docs for a release, the section of the getting started
that lets the user `west init` their workspace now has them check out
the version matchin the release.
Fixeszephyrproject-rtos/zephyr#92163
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
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>
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>
Add a new extension config value so that repo URL is not hardcoded in
the extension code.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Modify the extension so that multiple Doxygen projects can be
referenced. While not required in upstream Zephyr, other users
downstream may require support for this feature.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Modify the extension so that multiple Doxygen projects can be added.
While not required in upstream Zephyr, other users downstream may
require support for this feature.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The extension had a some major design flaws, mainly:
- Ignored the `api_overview_doxygen_xml_dir` setting, instead it
"sniffed" doxyrunner properties, so violating environment boundaries
- Computation of Doxygen HTML path worked because of the hardcoded URL
in relative form found in doc/conf.py
This patch moves most code to the actual directive, so that context can
be obtained from the document being parsed. Also, the only config
required now is the Doxygen output dir, obtained from doxyrunner at
conf.py level.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
remove Zephyr v3.6.0 from the list of supported releases. Zephyr v3.6.0
reached end-of-life on 2024-11-29.
Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>
Add a check to ensure that all zephyr_file/zephyr_raw links are pointing
to valid paths in the current zephyr tree.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This hooks up the dark-mode-toggle-stylesheets-loader so that the dark
mode styles are loaded immediately, rather than waiting for the page to
load and then switching to dark mode. This prevents the "flashing" of
light mode styles on page load.
Fixes#79791
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>
Increase navigation depth by 1 to enable "local" toc navigation in the
side bar for those pages that are deeper in the documentation tree.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Add Doxygen tooltips in the main documentation.
The tooltips are triggered when hovering over C symbols in the
documentation and display a preview of the Doxygen documentation for the
symbol.
Some shadow DOM magic is needed to style the tooltips correctly, without
affecting the rest of the page.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
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 extension was created to overcome C domain/Breathe limitations.
This is no longer needed as we link directly to Doxygen pages.
Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
3.5.0 went out of support end of August.
Note the end date was stated as either 2024/07/31 or 2024/07/26
in different places.
Signed-off-by: Alberto Escolar Piedras <alberto.escolar.piedras@nordicsemi.no>
Adds v3.7.0 to the list of supported releases.
The EOL data is currently set as 2.5 years after release
which is the minimum support period we claim.
Signed-off-by: Alberto Escolar Piedras <alberto.escolar.piedras@nordicsemi.no>
With the new Bluetooth Qualification process the QDID and link to
launchstudio are outdated, remove them.
Also remove the ICS listing as it hasn't been updated for a while.
Instead add a download link to the Zephyr Bluetooth Host ICS file.
Update the documentation configuration script to include the ICS file
(`*.pts`) in the external contents.
Signed-off-by: Théo Battrel <theo.battrel@nordicsemi.no>
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>
Generate a sitemap.xml for the documentation.
This aims at helping search engines react faster to the addition/removal
of new pages.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
A new extension, api_overview.py, is used to, leveraging doxygen's
Python module doxmlparser, parse the doxygen generated XML files.
All groups ('defgroup' and 'addtogroup' tags) are collected, alongside
their 'version' and 'since' info.
From there, a new Sphinx directive `api-overview-table` is populated,
including the name of the group, and if available, their 'since' and
'version' information.
Signed-off-by: Ederson de Souza <ederson.desouza@intel.com>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Adds v3.6.0 to the list of supported releases. The EOL date corresponds
to the expected release date for v4.0.0.
Signed-off-by: Maureen Helm <maureen.helm@analog.com>
This creates a set of substitution rules to replace all current usages
of SDK versions in the documentation, apart from a few that were not
meant to be copy-pastable anyway and the version has just been swapped
with a <version> placeholder.
Since code-block does not parse the content, these have all been
replaced with parsed-literal. That one though parses URLs, which cannot
be broken, so a series of URL substitutions are provided too.
Signed-off-by: Fabio Baltieri <fabiobaltieri@google.com>
So that external users of the domain only interested in e.g. referencing
roles, can skip tweaks made to Breathe's directives.
Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
Add UI to select preferred search engine when Google Programmable Search is
enabled. The user's preference is saved using local storage.
This also makes the search input field of type "search" for better UX (in
particular on mobile).
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Add Google Programmable Search engine to the documentation, while
leaving it possible to easily revert to the built-in Sphinx search
engine. As the styling of the search results is apparently not thought
to be easy to tweak, the gcs.css stylesheet might require further
improvements.
Fixes#55173.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This picks up custom javscript from Godot documentation and uses CSS
rules we already had in place (only they were not used) to tweak the
page scroll behavior. As folks scroll down the page, the Zephyr logo in
the top right corner gradually disappears, leaving more room for the
navigation menu.
Also, when scrolling in the navigation pane, the UI there is slightly
adapted to make it more clear that the search box is "fixed", plus,
when one reaches the bottom of the navigation tree and continues
scrolling, the "main" page scrolls down.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Improve documentation about pytest integration with Twister. Add
examples of usage, improve description of available options and
introduce automatic doc generation of two plugin classes (DeviceAdapter
and Shell) basing on their docstrings from source code.
Signed-off-by: Piotr Golyzniak <piotr.golyzniak@nordicsemi.no>
This commit loads the RTD theme as a Sphinx extension, which has the
benefit of going through said extension's "setup" method, effectively
setting useful settings such as default permalink icon (moving away from
the default, not so pretty, "¶").
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The index at the end of the PDF document can contain pretty long strings
that don't fit in the default 2-column layout.
This commit makes the index use a single-column.
Note: this relies on LaTeX package idxlayout which should already be
included in the packages recommended for installation in our
instructions.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
- Add extension to get git metadata (date, SHA-1, ...) regarding the
latest update made to a page
- Add date of last "actual" update to each manually authored doc page
- Add admonition inviting to report issues
- Add button in breadcrumb to report issue
Fixes#60622.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Update the vcs_link extension to also support generating "edit" URL
vcs_link_version is also now a Sphinx config making its value available
to extensions.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Force code blocks with no 'language' explicitly set to render with no
highlighting. The current default was to use python (bad), and there
would also be an option to set it to "guess" but this doesn't work all
so well (ex. some C blocks would be detected as Transact-SQL!).
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Use Noto as baseline font and Inconsolata Nerd Font for source code.
These are both esthetically pleasing and have good Unicode coverage.
NOTE: Unsupported characters (i.e. emojis, at the time of this commit)
are rendered as tofu (i.e. a square).
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
XeLaTeX is a TeX typesetting engine that extends LaTeX with support for
Unicode and modern font technologies such as OpenType.
It is included in all the LaTeX distro recommended for Zephyr so it is
safe to assume it is available to the user interested in building the
PDF documentation locally
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Benjamin Cabé
Aksel Skauge Mellbye
Fabio Baltieri
Fabian Blatz
Henrik Brix Andersen
Gerard Marull-Paretas
Mahesh Mahadevan
Jordan Yates
Gerard Marull-Paretas
Alberto Escolar Piedras
Théo Battrel
Ederson de Souza
Christopher Friedt
Maureen Helm
Piotr Golyzniak
Johan Hedberg