From e6422c44f99cd91e9824a18766aab65a413f6bd1 Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Tue, 3 Mar 2026 07:38:15 +0100 Subject: [PATCH] Add spell checker to Sphinx docs Add Doug's `sphinxcontrib.spelling` to Sphinx documentation builds. The plugin uses Enchant to check documentation for spelling errors. Fix a bunch of typos in documentation and code. Add `spelling_wordlist.txt` to teach the spell checker technical terms like cheeseshop, fromager, and traceback. Signed-off-by: Christian Heimes --- docs/conf.py | 8 ++- docs/customization.md | 2 +- docs/files.md | 2 +- docs/getting-started.rst | 2 +- docs/how-tos/containers.rst | 2 +- docs/spelling_wordlist.txt | 81 ++++++++++++++++++++++++++++ pyproject.toml | 1 + src/fromager/__main__.py | 2 +- src/fromager/commands/build_order.py | 2 +- 9 files changed, 95 insertions(+), 7 deletions(-) create mode 100644 docs/spelling_wordlist.txt diff --git a/docs/conf.py b/docs/conf.py index 7343676b..c1629367 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,6 +28,7 @@ "sphinxcontrib.autodoc_pydantic", "sphinx.ext.autodoc", "sphinx.ext.intersphinx", + "sphinxcontrib.spelling", ] # Enable MyST extensions to support reStructuredText directives in Markdown @@ -54,6 +55,11 @@ # "pyproject-hooks": ("https://pyproject-hooks.readthedocs.io/en/latest/", None), } +# sphinxcontrib.spelling settings +# File references a function object. Spell checker complaints about typo in +# random object id. +spelling_exclude_patterns = ["config-reference.rst"] + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output @@ -76,7 +82,7 @@ class FromagerHookDocumenter(FunctionDocumenter): objtype = "fromagerhook" - def format_name(self): + def format_name(self) -> str: name = super().format_name() if name.startswith("default_"): name = name[8:] diff --git a/docs/customization.md b/docs/customization.md index d5bead58..a6af38ee 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -97,7 +97,7 @@ support templating. The only supported template variable are: ### Resolver dist The source distribution index server used by the package resolver can -be overriden for a particular package. The resolver can also be told +be overridden for a particular package. The resolver can also be told to whether include wheels or sdist sources while trying to resolve the package. Templating is not supported here. diff --git a/docs/files.md b/docs/files.md index f48f8e41..af521ba8 100644 --- a/docs/files.md +++ b/docs/files.md @@ -157,7 +157,7 @@ wheels-repo └── simple ``` -* The `build` sub-directoy holds temporary builds. We use it as the output directory when building the wheel because we can't predict the filename, and so using an empty directory with a name we know gives us a way to find the file and move it into the `downloads` directory after it's built +* The `build` sub-directory holds temporary builds. We use it as the output directory when building the wheel because we can't predict the filename, and so using an empty directory with a name we know gives us a way to find the file and move it into the `downloads` directory after it's built * The `downloads` sub-directory contains the wheels in `.whl` format that fromager builds combined with the pre-built wheels so we can create a local package index in `simple` * The `prebuilt` sub-directory contains wheels that are being used as prebuilt * The `simple` sub-directory is laid out as a simple local wheel index. diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 01583051..481f3ab0 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -116,5 +116,5 @@ The output below is redacted for brevity. Missing sections are replaced with ``. 11:19:56 INFO Bootstrapping typing-extensions==4.14.0 took 0:00:01 total, 0:00:00 to resolve source, 0:00:00 to download source, 0:00:00 to prepare source, 0:00:00 to build sdist, 0:00:00 to add extra metadata to wheels, 0:00:00 to build wheels As each dependency is built, fromager will show output from the build process -and progress information. At the end of the build, fromager shows the lsit of +and progress information. At the end of the build, fromager shows the list of packages that were built and how long each step took. diff --git a/docs/how-tos/containers.rst b/docs/how-tos/containers.rst index 5d6b9882..fa972147 100644 --- a/docs/how-tos/containers.rst +++ b/docs/how-tos/containers.rst @@ -227,6 +227,6 @@ followed by the wheel being built successfully. pydantic-core: built wheel for version 2.18.4: /work/bootstrap-output/wheels-repo/downloads/pydantic_core-2.18.4-0-cp311-cp311-linux_x86_64.whl The :doc:`customization` section explains other techniques for changing the -build inputs to ensure packages build properley. The collection of wheels you +build inputs to ensure packages build properly. The collection of wheels you want to build may have different build-time issues, but you can use this iterative approach to work your way though them until they all build. diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt new file mode 100644 index 00000000..ee5b751a --- /dev/null +++ b/docs/spelling_wordlist.txt @@ -0,0 +1,81 @@ +args +backend +backends +backoff +canonicalize +canonicalized +changelog +changelogs +cheeseshop +cn +codebase +config +containerfile +cpu +csv +customizations +cython +deprecations +dir +downloader +env +environ +filesystem +fromager +frontend +frontends +graphviz +gz +installability +iterable +iteratively +json +lexicographically +linter +localhost +matcher +mypy +namespace +numpy +openssl +platlib +podman +pre +prebuilt +purelib +py +pydantic +pypi +pyproject +recurses +repo +scm +sdist +sdists +setuptools +statelessly +stderr +stdin +stdout +subcommands +subdirectory +submodule +submodules +subprocesses +templating +toml +toplevel +tos +traceback +tracebacks +txt +unshare +url +urls +vendored +vendoring +versionless +virtualenv +walkthrough +whitespace +yaml diff --git a/pyproject.toml b/pyproject.toml index de076a78..acc539c8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -84,6 +84,7 @@ docs = [ "myst-parser", "sphinx-rtd-theme", "autodoc-pydantic", + "sphinxcontrib.spelling", ] [project.urls] diff --git a/src/fromager/__main__.py b/src/fromager/__main__.py index 437fdae5..a2d4d891 100644 --- a/src/fromager/__main__.py +++ b/src/fromager/__main__.py @@ -140,7 +140,7 @@ @click.option( "--network-isolation/--no-network-isolation", default=SUPPORTS_NETWORK_ISOLATION, - help="Build sdist and wheen with network isolation (unshare -cn)", + help="Build sdist and when with network isolation (unshare -cn)", show_default=True, ) @click.pass_context diff --git a/src/fromager/commands/build_order.py b/src/fromager/commands/build_order.py index c5f2b601..88782c4e 100644 --- a/src/fromager/commands/build_order.py +++ b/src/fromager/commands/build_order.py @@ -31,7 +31,7 @@ def as_csv(build_order_file: str, output: pathlib.Path | None) -> None: Creates a file suitable for import into a spreadsheet including the distribution name, version, original requirement, dependency type, whether the package is pre-built, the build order step number, and - a full dependency chain leading to the requirment. + a full dependency chain leading to the requirement. """ fields = [