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>
Instead of breathe.
I'm not sure of the best version comparison to use. There is no
intention to break the API for docleaf but it is also still young
in some ways and there might be adjustments to the configuration values
that would need to be reflected in the version number as it is still
pre-1.0 that would only be a minor version change.
Signed-off-by: Michael Jones <m.pricejones@gmail.com>
Sphinx 5.2.0.post0 release has a known compatibility issue with the
`sphinx_rtd_theme` (see the issue readthedocs/sphinx_rtd_theme#1343).
Revert this commit once this compatibility issue is resolved.
Signed-off-by: Stephanos Ioannidis <root@stephanos.io>
Update to Sphinx 5.x, also update breathe since version 4.34 is the
first to officially support Sphinx 5.x.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
The sphinx-copybutton extension adds a button to every code snippet
that, when clicked, copies the code to the clipboard.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Looks like the 4.33 release has some more issues, so let's wait until
everything gets fixed before allowing future versions.
Ref. https://github.com/michaeljones/breathe/issues/805
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Sphinx 4.33.0 introduces Graphviz support, but the Graphviz
configuration value names clash with the Sphinx built-in Graphviz
extension.
Issue: https://github.com/michaeljones/breathe/issues/803
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
breathe: for simplicity, require versions > 4.30 (lower versions have
known issues, so do not take risks).
Sphinx: start requiring versions >=4.x. Keep with compatible versions,
since Sphinx major updrages can easily break extensions, themes, etc.
sphinx_rtd_theme: upgrade to >=1.x. Again, keep with compatible versions
since we have style customizations that can likely break on major
upgrades.
pygments: Allow any version >=2.9 (version that introduced DT support).
We do not have strong compatibility requirements here.
sphinx-notfound-page: Remove any requirements, we do not have strong
requirements for this one.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This means a light requirements-doc.txt is enough for doc writers. See
previous discussions in PR #31199 and PR #31239
Signed-off-by: Marc Herbert <marc.herbert@intel.com>
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>
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>
Breathe project has released version 4.29.1, a fix release for the
issues found in 4.29.0. Relax version requirements by just skipping the
buggy version and staying to compatible releases.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
docutils is a core dependency of Sphinx. It is only used by some of our
custom Sphinx extensions.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Allow versions starting from 0.5.2 up to < 1.0, be the next major
releases. Major releases tend to include breaking changes, so better
restrict such releases until they are manually tested for potential
regressions.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
We have recently been hit by an issue between docutils and
sphinx_rtd_theme. The problem is fixed since release 0.5.2. In order to
avoid similar problems in the future, pin the theme version.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Require Sphinx<3.4.0 to avoid the issue described in:
https://github.com/sphinx-doc/sphinx/issues/8603
This requirement can be relaxed once a new sphinx-rtd-theme is
released.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
The filters were updated to match the 3.3.0 generated text, so update
the sphinx requirement to exclude versions that use different text.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
Breathe>=4.23.0 brings in basic xrefitem rendering support and fixes
issues parsing anonymous struct/unions. This version also adds a config
knob for showing or hiding enumerator values, so set it to generate
documentation compatible with previous versions.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
Breathe 4.21.0 brings a few interesting features that improve the
generated documentation:
* A new `separate_member_pages` config option that patches issues in the
Doxygen XML generated when SEPARATE_MEMBER_PAGES option is YES.
* A new rST verbatim mode that allows producing inline elements.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
breathe v4.15.0 was just released and fixes some compatibility issues
with latest sphinx, the combo works, however with many warnings that we
still need to either fix or whitelist. This is temporary until we are
able to use those new versions.
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Version 3.0.0 release recently break doc build, lock version of sphinx
to something compatible while we upgrade dependencies...
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
Split up requirements.txt into several files so that CI tools can
utilize/reference the specific requirements-<FOO>.txt they may need
while keep things in sync with the development. This is to reduce
both time and amount of work CI actions due to python package install.
Create the following groupings:
1. BASE - needed to build or create zephyr images
2. BUILD-TEST - need to run compile/build tests
3. DOC - need to build the docs
4. RUN-TEST - need for runtime testing
5. EXTRAS - optional or useful for development/developers workflow
Also tried to add a comment about what or why a given package is being
pulled in for.
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>
