Skip to content

doc: add minimal sphinx tag that turns off very slow features #55708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

doc: add minimal sphinx tag that turns off very slow features #55708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,16 @@ DT_TURBO_MODE ?= 0
html-fast:
${MAKE} html DT_TURBO_MODE=1

# The `minimal` tag turns off all slow sphinx features for a much faster
# incremental build when editing .rst files interactively. As usual when
# making significant sphinx configuration changes, you must delete
# doc/_build/ first. WARNING: doxygen integration (breathe) will be
# missing, so building from scratch will print a LOT of warnings!
# However this is very useful for small, drive-by .rst fixes.
Comment on lines +22 to +24
Copy link
Member

@gmarull gmarull May 25, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think a build with lots of warnings is a good idea. All fast modes we've had until now have produced clean builds, so I think we should do the same here.

Copy link
Contributor Author

@marc-hb marc-hb May 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All fast modes we've had

Any other mode besides html-fast? Which is... too slow for interactive use.

This new "minimal" mode does not have to be official or documented. I can remove the new target and go back to just the sphinx tag. We just need something usable that does not require a code change.

What alternative(s) do you recommend?

Copy link
Member

@gmarull gmarull May 26, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All fast modes we've had

Any other mode besides html-fast? Which is... too slow for interactive use.

This new "minimal" mode does not have to be official or documented. I can remove the new target and go back to just the sphinx tag. We just need something usable that does not require a code change.

Why not official or documented?

What alternative(s) do you recommend?

Solve the warnings problem, or, try to contribute upstream to improve the extensions that are causing this issue. I also think that if an extension requires us to do such hackery, we should probably reconsider its usage unless it can be fixed.

Copy link
Contributor Author

@marc-hb marc-hb May 26, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not official or documented?

Because disabling breathe triggers a lot of breathe warnings (which are harmless when you don't care about breathe and just want to make some .rst changes)

try to contribute upstream to improve the extensions that are causing this issue. I also think that if an extension requires us to do such hackery, we should probably reconsider its usage unless it can be fixed.

This PR provides a massive improvement with just one if conditional. It's well tested and working now. These alternatives represent at least months of work for uncertain results. They're not really "alternatives".

... or solve the warnings problem

I could try to filter them out, would that work for you?

Copy link
Contributor

@keith-zephyr keith-zephyr May 31, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be okay with filtering the doxygen and kconfig warnings. The documentation should clearly state that the "minimal" option bypasses all doxygen and kconfig reference generation.

Copy link
Contributor Author

@marc-hb marc-hb Jun 28, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be okay with filtering the doxygen and kconfig warnings.

Thanks, I will try to find some time and do that in July.

html-minimal:
${MAKE} html DT_TURBO_MODE=1 SPHINXOPTS='-t minimal ${SPHINXOPTS}'


html latex pdf linkcheck doxygen: configure
cmake --build ${BUILDDIR} --target $@

Expand Down
10 changes: 8 additions & 2 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,14 +67,12 @@
# -- General configuration ------------------------------------------------

extensions = [
"breathe",
"sphinx.ext.todo",
"sphinx.ext.extlinks",
"sphinx.ext.autodoc",
"sphinx.ext.graphviz",
"zephyr.application",
"zephyr.html_redirects",
"zephyr.kconfig",
"zephyr.dtcompatible-role",
"zephyr.link-roles",
"sphinx_tabs.tabs",
Expand All @@ -86,6 +84,14 @@
"zephyr.external_content",
]

# List of semi-optional features that make the incremental build
# and/or the build from scratch significantly slower.
if not tags.has("minimal"): # pylint: disable=undefined-variable
extensions += [
"breathe",
"zephyr.kconfig",
]

# Only use SVG converter when it is really needed, e.g. LaTeX.
if tags.has("svgconvert"): # pylint: disable=undefined-variable
extensions.append("sphinxcontrib.rsvgconverter")
Expand Down