Skip to content

Commit

Permalink
docs: Fix config option for spelling filters
Browse files Browse the repository at this point in the history
We've been using a custom spelling filter to make sure that "WireGuard"
is spelled correctly, with the proper case. As it turns out, passing
this filter to the Sphinx configuration, in the conf.py file, makes
Sphinx re-read all sources and re-write all output files, as can be
observed when running sphinx-build multiple times, without suppressing
the output:

    $ sphinx-build -M html . _build
    [...]
    updating environment: [config changed ('spelling_filters')] 472 added, 30 changed, 0 removed
    [...]

This is because in conf.py, we pass the filter directly as a function.
When Sphinx writes its environment.pickle file to keep track of the
configuration in use, it discards values that cannot be serialised,
including the filter, "<class 'cilium_spellfilters.WireGuardFilter'>",
of instance "type" [0]. So the value for the configuration option
"spelling_filters" is not saved, and as Sphinx believes that the
configuration has changed, it reads and rebuilds everything.

In fact, the issue has been reported before, and solved in the
spellchecker [1]. We need to set the configuration with a string instead
of the direct function object, and the extension is able to load it from
there. Let's adjust accordingly, to save cycles when building the docs
more than once.

[0] https://github.com/sphinx-doc/sphinx/blob/v7.1.2/sphinx/config.py#L323
[1] sphinx-contrib/spelling#40

Signed-off-by: Quentin Monnet <quentin@isovalent.com>
  • Loading branch information
qmonnet authored and ti-mo committed Aug 17, 2023
1 parent 0294781 commit 270be30
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion Documentation/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@
spelling_exclude_patterns = ['_api/v1/*/README.md']

# Add custom filters for spell checks.
spelling_filters = [cilium_spellfilters.WireGuardFilter]
spelling_filters = ["cilium_spellfilters.WireGuardFilter"]

# Ignore some warnings from MyST parser
suppress_warnings = ['myst.header']
Expand Down

0 comments on commit 270be30

Please sign in to comment.