Skip to content

Fail the docs build on quick index config problems - #2967

Merged
pvcraven merged 1 commit into
developmentfrom
quick-index-strict
Oct 9, 2026
Merged

pvcraven merged 1 commit into
developmentfrom
quick-index-strict

Conversation

@pvcraven

@pvcraven pvcraven commented Oct 9, 2026

Copy link
Copy Markdown
Member

Closes #2800

Problem

CI builds the docs with -W, so Sphinx's own warnings fail the build. doc/conf.py also runs util/update_quick_index.py to generate the API pages, and that script reported problems with print(), so they never failed anything. These included:

  • "No members parsed for …", for a config entry that adds nothing to the docs
  • "Failed to open …"
  • "Exception processing …"
  • "Unintelligible config data …", which also skips writing that page

A config entry for a module that doesn't exist already failed the build, because get_module_path raises.

Change

  • The script now collects these problems and raises a RuntimeError at the end listing all of them. That stops the Sphinx build, and running the script on its own exits with an error.
  • Removed the 7 config entries that caused the current "No members parsed" warnings:
    • arcade.sprite_list, arcade.texture, arcade.texture_atlas, arcade.anim and arcade.gui, whose __init__.py files only re-export names from submodules that are already listed
    • arcade.__main__, which has no classes or functions
    • arcade.types.numbers, which only defines the type alias AsFloat, and the parser only finds class and def
  • AsFloat wasn't documented anywhere. A new "data" config option lists names to document with autodata. The types page uses it for arcade.types.numbers.AsFloat, which now appears on the page and in the quick index.
    • It's listed by its defining module because autodoc reads #: comments from there. Through the arcade.types re-export, it showed Python's built-in "Represent a PEP 604 union type" text.
    • Its comment now says what it is: "A float or an int. Arcade accepts either where it uses this type, and works with the value as a float."

The other type aliases in arcade.types (Point2, RGBA255, Velocity and so on) aren't documented either. They can be added to "data" later.

Testing

  • The docs build with -W passes with no warnings, and the 7 "No members parsed" lines are gone.
  • Adding arcade.types.numbers back to the config makes the build fail, with the problem listed in the error.
  • I checked the rendered AsFloat entry on the types page.
  • ruff and mypy pass.

🤖 Generated with Claude Code

update_quick_index.py printed its warnings, so Sphinx never saw them and
the build passed. It now collects them and raises at the end, which
stops the build. Removes the seven config entries that produced the
"No members parsed" warnings: re-export-only __init__ files, __main__,
and arcade.types.numbers. AsFloat, the only thing in numbers.py, is now
listed by name with a new "data" option and has a real description.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pvcraven
pvcraven merged commit bdb95c2 into development Oct 9, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Warning handling in doc build is inconsistent

1 participant