Skip to content

docs: complete add_js_file and add_css_file documentation - #14660

Open
cnbei wants to merge 1 commit into
sphinx-doc:masterfrom
cnbei:cursor/docs-add-js-css-file-5e9d
Open

docs: complete add_js_file and add_css_file documentation#14660
cnbei wants to merge 1 commit into
sphinx-doc:masterfrom
cnbei:cursor/docs-add-js-css-file-5e9d

Conversation

@cnbei

@cnbei cnbei commented Aug 30, 2026

Copy link
Copy Markdown

Purpose

Fill the remaining gaps in the Sphinx.add_js_file() and Sphinx.add_css_file() docstrings reported in #12223:

  • Show the CRC32 cache-busting query parameter (?v=) in the examples (added in Append CRC32 checksum to asset URIs #11415 / Sphinx 7.1).
  • Add versionchanged:: 7.1 notes for that checksum.
  • Explain that these methods only emit the HTML tag; local files still have to land in _static via add_static_dir() (extensions) or html_static_path (site authors).
  • Point site authors at html_js_files / html_css_files with html_static_path.

This is a new PR, not a continuation of #14322.

No CHANGES.rst entry (documentation-only).

References

Closes #12223.

AI Disclosure

A Cursor Cloud Agent prepared this change at the requester's instruction.

  • Tools: Cursor Cloud Agent. Used to read Incomplete documentation for add_js_file() and add_css_file() #12223, the current add_js_file / add_css_file docstrings, the HTML builder checksum implementation, add_static_dir, and the html_js_files / html_css_files / html_static_path confvals, then draft the docstring additions.
  • What is AI-generated: the new paragraphs, example ?v= suffixes, versionchanged 7.1 notes, expanded seealso lines in sphinx/application.py, and this pull request body.
  • What is not: no runtime code was changed. The wording was checked against the implementation.
  • Improve documentation for add_js_file() and add_css_file() #14322 was read only to avoid duplicating it; this text was written separately.

I have read https://www.sphinx-doc.org/en/master/internals/ai-policy.html.

…d_css_file

Co-authored-by: cnbei <baymy@foxmail.com>
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.

Incomplete documentation for add_js_file() and add_css_file()

2 participants