Commit Graph

158 Commits

Author SHA1 Message Date
Gerard Marull-Paretas b4f968cf9d doc: add a toctree with reference material
Add a new toctree with reference material, including:

- API docs (Doxygen)
- Kconfig options
- Devicetree bindings

Note that the toctree is rendered manually due to the limitations Sphinx
has when it comes to including relative URLs. Hardcoding absolute URLs
in toctrees is possible, but that means we'd need to update the toctree
on every release (to point to /version/ URL), and downstream users of
the documentation would have to manually patch the toctree with their
own URL. In order to make local builds work, version prefix is only
added if publish tag is provided.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-11-02 13:24:40 +01:00
Gerard Marull-Paretas fe7529f917 doc: enable vcs_link extension
Enable the vcs_link extension so that pages contain "Open on Github"
link at the top.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-10-26 17:00:56 +02:00
Gerard Marull-Paretas 4516117e9f doc: enable figures enumeration
Enable figures enumeration. This option allows to use :numref: in order
to reference figures, thus allowing more precise references other than
"the figure below" or similar.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-10-25 15:26:47 -05:00
Gerard Marull-Paretas d7b7bb1e75 doc: drop 2.2.0 version
Drop the 2.2.0 version entry so that its link is removed from the docs
drop-down list.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-10-19 12:08:04 -04:00
Gerard Marull-Paretas 9130455677 doc: add 2.7.0 release to versions list
Add 2.7.0 to the version list so that a link to it is created on the
documentation drop-down list.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-10-19 12:08:04 -04:00
Gerard Marull-Paretas a42ee8bd04 doc: doxygen: add version and shorten brief
Render Zephyr version in both, standalone Doxygen build and Sphinx
controlled build. In standalone mode, the package version given by
find_package(Zephyr...) is used, while in Sphinx build the conf.py
version is used.

The project brief has been shortened to make project title more compact
while still containing relevant information.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-10-07 11:54:23 -04:00
Gerard Marull-Paretas 2f5a9d033d doc: improve latex look and feel
This patch improves the general look and feel of the LaTeX (PDF)
documentation build. Changes include:

- A custom title with relevant information has been created
- Some colors have been adjusted to match those in the web template
- Charter font family is used

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-07-22 19:37:03 +03:00
Gerard Marull-Paretas 1829dc8875 doc: do not use env vars to discover paths
ZEPHYR_BASE and ZEPHYR_BUILD directories were passed to Sphinx via
environment variables. However, these paths can be easily discovered by
the conf.py file itself. As a result, Sphinx is less dependent on CMake
to operate.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-07-21 07:28:18 -04:00
Gerard Marull-Paretas 4127138475 doc: enable graphviz extension
Enable the built-in Sphinx Graphviz extension to allow creating Graphviz
diagrams natively on the source files. Some style defaults have been
enabled to make sure diagrams are consistent and have good quality in
both light and dark modes.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-07-20 19:54:52 -04:00
Gerard Marull-Paretas 1cecfe7348 doc: move favicon to static folder
Similar to other assets, e.g. logo, move favicon to the static folder.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-07-19 20:06:00 -04:00
Anas Nashif cadd062ce4 doc: create an index for PDF files
Most of the content in the default index is HTML only, so create an
index just for PDF and keep it clean.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
2021-07-15 07:07:21 -04:00
Gerard Marull-Paretas a9b1c42f40 doc: extensions: remove eager_only
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>
2021-06-30 08:29:01 -04:00
Gerard Marull-Paretas 9dfbdf1997 doc: use kconfig role and directive
Stop using :option: for Kconfig options.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-06-29 10:26:28 -04:00
Gerard Marull-Paretas 45cce736e2 doc: fix notfound prefix for latest docs
The notfound extension prefix was incorrect for 'latest' docs version.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-06-22 06:34:51 -04:00
Kumar Gala 79a6c07536 release: Updates for v2.6.0
VERSION and conf.py updates for v2.6.0 release

Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
2021-06-04 16:07:47 -05:00
Gerard Marull-Paretas 4dd15539a9 doc: use external_content
Use external_content Sphinx extensions to gather documentation sources.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-25 19:38:11 +02:00
Gerard Marull-Paretas 830de4c905 doc: conf: remove unused breathe project
the `doc-examples` project is not used and, in fact, is a duplicate of
the Zephyr project.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-20 20:04:51 +02:00
Gerard Marull-Paretas 2d06ad7ee4 doc: make some Sphinx config path absolute
Make all paths absolute.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-20 20:04:51 +02:00
Gerard Marull-Paretas 95d8d2cc58 doc: fix 404 page
Sphinx handling of 404 page is not that easy when using theme
customizations. Enabled the `sphinx-notfound-page` extension (maintained
by readthedocs) to fix its displaying.

Also adjusted Zephyr logo (was causing some Sphinx processing errors
when trying to scale it).

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-19 16:48:39 -04:00
Gerard Marull-Paretas 073c8cf849 doc: remove scrolling customizations
The scrolling customizations were used to hide the logo when scrolling
down. With this change, logo is always displayed.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-19 16:48:39 -04:00
Gerard Marull-Paretas f0d3db29ed doc: show logo only
Since logo already brings to home page, remove the link displayed above.
It saves some vertical pixels while making docs nicer. Also adjusted
wy-menu-vertical max-height to account for the new height (note: was
wrong before).

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-19 16:48:39 -04:00
Gerard Marull-Paretas 0e503418ad doc: enable members option by default when using breathe
Enable the :members: option by default when using breathe directives.
This exposes automatically stuff like structure fields.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-19 06:21:53 -04:00
Gerard Marull-Paretas aad84e702a doc: doxygen: do not use separate member pages
When this option is enabled some data structures have missing pages. Use
the default setting (NO).

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-19 06:21:53 -04:00
Gerard Marull-Paretas 457f3a46d6 doc: use doxyrunner
doxyrunner plugin replaces a series of CMake+Python hacks. These include
input changes tracking and incremental build output simulation.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-06 13:19:19 +02:00
Gerard Marull-Paretas aa0b02bf75 doc: use pygments devicetree language support
Since Pygments 2.7.0 devicetree syntax is supported, so there is no need
to use a custom lexer. Version 2.9.0 introduces a fix that is required
for some devicetree snippets.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-05-04 22:42:15 -04:00
Gerard Marull-Paretas a6d8c232e0 doc: new look and feel
A new look and feel for the Zephyr documentation. It is largerly based
on the work done by Godot Engine docs, but with some Zephyr specific
customizations.

Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
2021-04-20 19:17:15 +02:00
Nicolas Pitre 0dc7b9ee46 k_current_get(): make it a "const" function
This function always returns the same value for a given thread.
Add the const attribute to it so the compiler won't call it over and
over needlessly each time _current is referenced, making for far more
efficient code.

The __attribute_const__ symbol is used to mimic the Linux equivalent.
We want to make it clear that this is distinct from the const keyword.

Fix the test_x86_cpu_scrubs_regs where the compiler wasn't told that a
bunch of registers are being clobbered as highlighted by this change.

Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
2021-04-14 20:32:05 -04:00
Gerard Marull-Paretas 96c7d10a15 doc: use warnings_filter
Replace current filter setup with the warnings_filter Sphinx extension.
Note that current regexes have been simplified to make them more
readable while keeping the most relevant information.

Sphinx warnings are now treated as errors (-W).

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-04-07 14:15:29 +02:00
Gerard Marull-Paretas f4edff068f doc: format configuration file
Format the configuration file so that it is more consistent (e.g.
uniform usage of single/double quotes).

Some minor cleanup performed too: removed some comments and a default
setting.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas 4b09faf4b9 doc: use pathlib for paths in configuration file
Switch to pathlib to make configuration more readable. sys.exit has been
replaced with an exception so that in case of failure error is displayed
(error details were hidden).

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas 7abf838394 doc: use regex to parse Zephyr version
Simplify the logic of version extraction by using regexes.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas d45079aca1 doc: remove unicode prefix from strings
This is not needed on Python 3.x as it's the default.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas 603e875ab8 doc: organize configuration sections better
Organize configuration sections per group (project, general, HTML,
plugin options...).

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas 0312b0ba7f doc: move imports to the top of the file
Some are not really at the top because of path inserts, but are as up as
possible.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas 4114d6e16b doc: simplify some html_context logic
Simplify is_release and docs_title logic and move it closer to where it
is used.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas 2b9b16360e doc: add configuration reference and remove parameter details
It is easy to have out-of-date comments since Sphinx settings evolve
(defaults, behavior...). A reference to the official documentation is
provided at the top of the file instead.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas c166f93442 doc: remove settings for unused builders
manpage, texinfo and htmlhelp builders are not used, so remove their
settings as they are redundant.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas b2469e1dec doc: move redirects to a utility module
Isolate the list of redirects in order to improve conf.py readability.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas 4d624c0a6e doc: remove Sphinx defaults
Remove settings that are Sphinx defaults in order to simplify
configuration.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas cbe7a78635 doc: remove commented options from config
Remove options that are commented out from conf.py. It improves
readability of the file.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas a4ea28236c doc: move all css files to _static/css
Move all CSS files to the _static/css subfolder.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas bbab8152ce doc: move all js files to _static/js
Move all Javascript files to the _static/js subfolder.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas 38b1f7a15e doc: move extensions to _extensions
Move all Sphinx related content to folders prefixed with an underscore.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Gerard Marull-Paretas 6b1a7faf92 doc: move static folder to _static
Move static content to _static. It is better to prefix all Sphinx
related folders with an underscore to emphasize that the folder does not
contain actual documentation. Static content gets copied into _static
folder when documentation is built, so it also makes things more
consistent.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
2021-03-31 10:39:48 +02:00
Martí Bolívar e4c0783bfd doc: add new :dtcompatible: role / directive
This allows RST documentation to do something like this:

   See :dtcompatible:`vnd,foo` for more information.

This is transformed into a link to documentation for the "vnd,foo"
compatible.

Some devicetree compatibles may be handled by multiple bindings.
This can happen when the binding file is bus-dependent. Therefore, to
make this work, we need to change the way gen_devicetree_rest.py works
to ensure we have a good source of information for this compatible
regardless of how many bindings are associated with as follows:

- When only a single binding is associated with a compatible, the
  :dtcompatible: link goes directly to the per-binding HTML page.

- When multiple bindings are associated with a compatible, this goes
  to a new generated "disambiguation" page which links to all the
  per-binding pages.

To avoid clashes, we stick the disambiguation pages into a
compatibles/ subdirectory of the generated bindings index root
directory.

Also reorganize the generated bindings output directory into
.../bindings/subdir/binding.rst files. For example,
dts/bindings/arm/arm,dtcm.yaml now gets its generated content in
.../bindings/arm/arm,dtcm.rst.

This brings the 'category' of binding (like 'sensor', 'i2c', etc.)
into the URL, which is a useful hint.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-03-29 16:33:51 +02:00
Mikkel Jakobsen 4cd0199406 doc: update doc footer copyright year
Update the documentation footer copyright year.

Signed-off-by: Mikkel Jakobsen <mikkel.aunsbjerg@prevas.dk>
2021-03-19 19:17:20 +01:00
Anas Nashif ccc185be63 doc: add 2.5.0 to pick list
Add 2.5 to release list to be shown on documentation side bar.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>
2021-02-14 09:58:55 -05:00
Martí Bolívar 673474b020 doc: clean up west index
Rename the 'basics' page to basics.rst, adding a redirect for the old
title.

Rearrange some other index pages to improve the flow:

- Put relatively stale content in moving-to-west.rst to the bottom. I
  expect pepole have either moved west or are choosing not to.

- Promote the release notes page higher up, since that seems more
  important.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-02-10 08:53:39 -05:00
Martí Bolívar e36fc11100 doc: sort redirects
Just to keep things easier to find.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
2021-02-10 08:53:39 -05:00
Gerson Fernando Budke 43a0dbe260 doc: guides: debugging: Move to flash_debug dir
The debugging section was generalized for flash and debugging tools.
The links were refactored accordly and all references were updated.
To be consistent, the directory doc/guides/debbugging was renamed to
doc/guides/flash_debug.

Signed-off-by: Gerson Fernando Budke <nandojve@gmail.com>
2020-12-03 10:50:23 -06:00