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>
The project charter has apparently changed location on
the main zephyrproject.org website.
This fixes a couple occurences of the old URL.
fixes#76433
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
Make a PR description an expectation/requirement for
pull requests submitted to the zephyr project.
Signed-off-by: Declan Snyder <declan.snyder@nxp.com>
Remove references to a timline for the coding guidelines enforcement
stages. Mark the current stage better and add notes about the
current stage.
Signed-off-by: Simon Hein <Shein@baumer.com>
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>
Restructure the Contribution Guidelines page in the documentation.
Create the 'Pull Request Guidelines' section containing the best
practices for creating Pull Requests.
Improve commit message guidelines: instruct contributors to refer to
GitHub issue in the PR message instead of commit message when
submitting a fix; add a description of `Link:` tags for refering to
other relevant information.
Move 'clang-format' and 'twister' subsections to the new PR
Guidelines section.
Delete outdated/incorrect information about how to run tests locally
with twister.
Describe the `check_compliance.py` script as the recommended tool for
checking compliance of changes and how to run the script locally.
Remove 'gitlint' subsection.
Add a list of recommended steps for getting a new PR accepted quickly.
Signed-off-by: Gustavo Silva <gustavograzs@gmail.com>
Clarification of reviewer expectations and role. Emphasis
on clarifying when a PR can be closed.
Highlighting reviewers and assignee objective to guide PR
to a mergeable state, if possible.
Signed-off-by: David Leach <david.leach@nxp.com>
- Adds -U upgrade flag to the install requirements command.
- Fixes a possible documentation generation issue,
reported in https://github.com/zephyrproject-rtos/zephyr/issues/73082
Signed-off-by: Andrej Butok <andrey.butok@nxp.com>
