Skip to content

docs: enable nitpicky mode to warn on broken references#2668

Open
krusta07 wants to merge 4 commits into
falconry:masterfrom
krusta07:fix/sphinx-nitpicky
Open

docs: enable nitpicky mode to warn on broken references#2668
krusta07 wants to merge 4 commits into
falconry:masterfrom
krusta07:fix/sphinx-nitpicky

Conversation

@krusta07

Copy link
Copy Markdown

Summary of Changes

Enabled nitpicky = True in docs/conf.py so Sphinx emits
warnings on broken references during documentation builds.

Also added nitpick_ignore entries for the three unresolved
type aliases (SyncMiddleware, AsyncMiddleware,
PreparedMiddlewareResult) that were already noted in a
TODO comment in the same file.

Related Issues

Closes #1888

Pull Request Checklist

  • Applied changes to both WSGI and ASGI code paths and interfaces (where applicable).
  • Added tests for changed code.
  • Performed automated tests and code quality checks by running tox.
  • Prefixed code comments with GitHub nick and an appropriate prefix.
  • Coding style is consistent with the rest of the framework.
  • Updated documentation for changed code.
    • Added docstrings for any new classes, functions, or modules.
    • Updated docstrings for any modifications to existing code.
    • Updated both WSGI and ASGI docs (where applicable).
    • Added references to new classes, functions, or modules to the relevant RST file under docs/.
    • Updated all relevant supporting documentation files under docs/.
    • A copyright notice is included at the top of any new modules.
    • Changed/added classes/methods/functions have appropriate directives.
  • Changes have towncrier news fragments under docs/_newsfragments/.
  • LLM output has been carefully reviewed and tested by a human developer.

@codecov

codecov Bot commented Jun 25, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (6a49881) to head (277097e).

Additional details and impacted files
@@            Coverage Diff            @@
##            master     #2668   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           64        64           
  Lines         7985      7985           
  Branches      1103      1103           
=========================================
  Hits          7985      7985           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@vytas7 vytas7 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Hi, and thanks for experimenting with this.
Unfortunately, bluntly enabling nitpicky like this results in hundreds of warnings...

Comment thread docs/conf.py
# Intersphinx configuration
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

# NOTE(vytas): Nitpicky mode is enabled to warn on broken references and

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Please do not impersonate me in the comments, use your own nick in the prefix.

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.

Doc: Explore Sphinx options if there is a flag to emit a warning on broken links

2 participants