Enhance the zephyr_file link role to support referencing specific lines
or line ranges in files.
This change allows users to link to exact locations within a file
using GitHub-style line references.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The button for rebasing PRs is not available anymore, so this note does
not apply and will only cause confusion, remove it.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Twister works on all OSes with different levels of features/targets
supported, so clarify the message.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Perl is required for check_compliance.py/checkpatch.pl, and needs to be
installed in Windows to run these scripts.
Signed-off-by: Derek Snell <derek.snell@nxp.com>
Introduce a new directive for displaying hardware features supported by
a board, using information available in the devicetree.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
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>
This is a follow-up from a recent debate on Discord about whether
splitting up related groups of properties is OK. Record the consensus
outcome of the debate so this question is easier to answer next time.
Signed-off-by: Martí Bolívar <marti.bolivar@oss.qualcomm.com>
Under the documentation generation sections, the path to the docs folder
and the zephyr path is inconsistent with the getting started pages.
Update to match
Signed-off-by: Mihira Madhava Bollapragada <madhava@ti.com>
Consolidate all style guidelines into one place, moving cmake style
guidelines under the contribute section.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Reviewer expectation was burried under contributor section, it deserves
to be on the same level and highlighted.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
The text in this note is not accurate and should already be covered by
the license agreement, no need to say what the license already covers in
non-legal terms.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Move some of the historical safety related language and
enforcement strategy re coding guidelines to the safety section.
The coding guidelines are and have been in effect for a while now,
but it seems this introduction text is confusing contributors.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This change was triggered by a review comment linked below:
https://github.com/zephyrproject-rtos/zephyr/pull/83117#issuecomment-2549120181
It extends the current Reviewer Expectations with additional rules
agreed upon by multiple Zephyr contributors in order to simplify and
standardize the decision-making process during PR reviews.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Clarify and extend some of the PR and contribution guidelines so that
they cover practices that have been effectively enforced by maintainers,
but were never properly documented.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
scripts/checkpatch.pl was written originally for the Linux kernel, and
its code reflects the kernel's coding style. In particular, it has
checks for unneeded braces around single-statement if/else/for/while
conditions. In Zephyr however, braces are always required, and so the
checks needed modifying to verify the opposite condition.
In order to enable the now-compatible checks, we also remove the
--ignore BRACES statement in .checkpatch.conf.
Limitations: the current code works well if there are not conditional
statements (e.g. #if, #ifdef or #endif) next to the if/else/for/while
conditions. This is rarely the case, but triggers with the Bluetooth
controller in code like this:
```
#if defined(CONFIG_BT_PERIPHERAL)
if (!lll->is_hdcd)
#endif /* CONFIG_BT_PERIPHERAL */
{
```
```
} else
#endif /* CONFIG_BT_CTLR_PRIVACY */
{
```
```
#if defined(CONFIG_BT_CTLR_DF_ADV_CTE_TX)
if (lll->cte_started) {
radio_switch_complete(phy_s, 0, phy_s, 0);
} else
#endif /* CONFIG_BT_CTLR_DF_ADV_CTE_TX */
{
```
```
#ifdef DUAL_BANK
while ((FLASH_STM32_REGS(dev)->SR1 & FLASH_SR_QW) ||
(FLASH_STM32_REGS(dev)->SR2 & FLASH_SR_QW))
#else
while (FLASH_STM32_REGS(dev)->SR1 & FLASH_SR_QW)
#endif
{
```
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Refrain from using Escalation language when requesting review and
getting awareness from maintainers.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Utilize a code spell-checking tool to scan for and correct spelling errors
in various files within the `doc` directory.
Signed-off-by: Pisit Sawangvonganan <pisit@ndrsolution.com>
.. target-notes:: is a useful directive that needs to explicitly be
included for a "References" section to really be useful. This commit
updates the doc guidelines accordingly to help ensure that future docs
are using it correctly.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This updates the documentation of all the Seeed Studio boards to use
the new `zephyr:board::` directive.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
A new zephyr:board:: Sphinx directive allows to flag a documentation
page as being the documentation for a specific board, allowing to
auto-populate some of the contents, ex. by adding a board overview a la
Wikipedia, and later things like supported HW features, etc.
A corresponding :zephyr:board: role allows to link to a board doc page.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Due to the (potentially) hard to understand effects of blobs, it seems
prudent to make their presence more noticeable.
Hopefully, this will make it easier to identify issues (such as those
reported on GitHub) that have been observed on devices running a tainted
build.
Signed-off-by: Reto Schneider <reto.schneider@husqvarnagroup.com>
While not visible in the rendered documentation, double spaces look bad
when reading plaintext file.
Signed-off-by: Reto Schneider <reto.schneider@husqvarnagroup.com>
This commit adds support for generating an interactive catalog of all
the supported boards that can be included in the documentation using
the `.. zephyr:board-catalog::` directive.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Fixes 78713
Add instructions to the "Git Setup" section to ensure that the user's
GitHub profile name is their full name (first and last) and that the
GitHub profile name and email address match the git config user.name
and user.email.
Page: contribute/guidelines
Tested with:
ninja html
python3 -m http.server 8000
Signed-off-by: Arrel Neumiller <rlneumiller@gmail.com>
This commit adds support for categorizing code samples in the
documentation.
It introduces two new directives:
- `zephyr:code-sample-category::` to create a category and associated
brief description, that implicitly acts as a toctree too.
- `zephyr:code-sample-listing::` to allow dumping a list of samples
corresponding to a category anywhere in the documentation.
Fixes#62453.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
- Improved document structure (was *very* flat before) by adding more
meaningful top-level headings and re-ordering some of the existing
sections
- Provide detailed and structured docs for all the custom Sphinx roles
and directives available in Zephyr, including moving the docs for
``.. zephyr-app-commands`` directive and `:dtcompatible:` roles away
from the extensions' source files to align with how Sphinx typically
handles docs for custom roles/directives.
- Added more content regarding diagrams guidelines, images,
cross-referencing of Doxygen documentation, ...
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Commit 204860857e (PR #41061) dropped
support for "any" as the default role, so this should be dropped from
the documentation guidelines as well.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Fixes bad usage of single backticks in lieu of double backticks for
rendering inline literals, or simple '*' for italics.
When appropriate, a better construct than double backticks has been
selected (ex. :file:, :kconfig:option:, :c:func:, ...), or proper :ref:
have been used if the original intention was to have a link.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This link probably never worked. This commit fixes the relative
URL to properly point to where Doxygen docs live.
Fixes#78016.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
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>
Refactor the guidelines rule table and add a zephyr rule number
to make it more clear that the coding guideline rules are a
subset of the MISRA-C:2012 rules.
Signed-off-by: Simon Hein <Shein@baumer.com>
Commit 698a0c3193 changed the bluetooth_api
section title, which made the reference in the Coding guidelines turn into
"API", which is confusing.
Use a fixed title for that reference to fix the issue.
Signed-off-by: Mathieu Choplain <mathieu.choplain@st.com>
Remove the references to the breathe extension in the
Schematic of the documentation build process graph and
the filtering expected warnings section.
Signed-off-by: Simon Hein <Shein@baumer.com>
