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>
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>
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>
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>
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>
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>
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>
- 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>
Correct a previous mistake indicating syntax highlighting is
autoguessed.
Add recommendations and samples around languages that documentation
authors are encouraged to use.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This commit fixes syntax higlighting of all the reStructuredText
snippets in the documentation guidelines by setting default
higlighting language to rst.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The "Contributing to Zephyr" page used to be a simple table of contents
with pointers to sub-pages. This bland page was not very inviting to new
contributors, and provided little to no context as to what to expect in
each sub-section. This commit improves the landing page by implenmenting
the following changes:
- Remove auto toctree and replace with manually curated entries that
provide more context about each sub-section.
- Add a section about the Zephyr Contributor Badge.
- Add a section about getting help, with links to Discord and dev
mailing list.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The intro of this document was starting to show its age. Simplified
some of the wording and added a reference to the documentation build
instructions.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
"Numbered steps" were dropped a long time ago in a previous revamp of
the stylesheet, so dropping instructions related to them in the
documentation guidelines.
Also remove unecessary mention to "how to build the doc" as it's
already mentioned as a note at the top of the document.
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
The Python dependencies specific to building the documentation were
recently removed from the common requirements. Point users to the
documentation generation instructions and provide details on installing
the doc specific dependencies.
Signed-off-by: Keith Short <keithshort@google.com>
Zephyr scripts do not require documentation dependencies, so let's
move them from scripts/ to doc/.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Zephyr's coding style is based on the Linux kernel coding style, which
indicates a preferred limit of 80 columns. Zephyr's .clang-format sets
the ColumnLimit to 100. Update the documentation to match the
.clang-format parameters.
Signed-off-by: Keith Short <keithshort@google.com>
This commit fixes the incorrect reference to the `doc/Makefile` and
updates the text to better integrate the reference.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit fixes incorrect depiction of the internal link with custom
text usage.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
This commit updates the documentation guidelines to reflect the
refactored documentation paths.
It also corrects the unnecessary escapes of the backticks.
Signed-off-by: Stephanos Ioannidis <stephanos.ioannidis@nordicsemi.no>
