From df09488a0d5381847dc6be37d1532fd1d1258faf Mon Sep 17 00:00:00 2001
From: Dhruvil Darji <dhruvildarji1409@gmail.com>
Date: Wed, 25 Feb 2026 10:16:00 -0800
Subject: [PATCH] Improve documentation for add_js_file() and add_css_file()

Address documentation gaps identified in #12223:

- Update examples to show CRC32 checksum query parameters (?v=...)
  that are appended to local asset URIs since Sphinx 7.1
- Add "versionchanged:: 7.1" notes documenting the checksum feature
- Add note explaining how JS/CSS files can be copied to _static
  (via add_static_dir for extensions, html_static_path for site authors)
- Add tip mentioning that site authors can use html_js_files and
  html_css_files config values with html_static_path as an alternative
  to writing an extension
- Add note about overriding extension files via html_static_path,
  with a caveat linking to #12096

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 sphinx/application.py | 66 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 5 deletions(-)

diff --git a/sphinx/application.py b/sphinx/application.py
index 5349c36ad42..b2a4c0d53fa 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -1461,14 +1461,38 @@ def add_js_file(
         Example::
 
             app.add_js_file('example.js')
-            # => <script src="_static/example.js"></script>
+            # => <script src="_static/example.js?v=a1b2c3d4"></script>
 
             app.add_js_file('example.js', loading_method='async')
-            # => <script src="_static/example.js" async="async"></script>
+            # => <script src="_static/example.js?v=a1b2c3d4" async="async"></script>
 
             app.add_js_file(None, body="var myVariable = 'foo';")
             # => <script>var myVariable = 'foo';</script>
 
+        .. note::
+
+           For the file to be included in the output, it must be present in
+           the ``_static`` directory at build time.
+           Extension developers should use :meth:`add_static_dir` to register
+           a directory whose contents will be copied to ``_static``.
+           Site authors can place files into a directory listed in
+           :confval:`html_static_path` instead.
+
+        .. tip::
+
+           Site authors (as opposed to extension developers) who wish to add
+           custom JavaScript files may find it easier to use the
+           :confval:`html_js_files` configuration value in combination with
+           :confval:`html_static_path`, rather than writing an extension.
+
+        .. note::
+
+           Files registered by extensions can be overridden by site authors
+           by placing a file with the same name into their
+           :confval:`html_static_path`. Note that this may not work in all
+           cases; see `#12096 <https://github.com/sphinx-doc/sphinx/issues/12096>`__
+           for details.
+
         .. list-table:: priority range for JavaScript files
            :widths: 20,80
 
@@ -1498,6 +1522,9 @@ def add_js_file(
         .. versionchanged:: 4.4
            Take loading_method argument.  Allow to change the loading method of the
            JavaScript file.
+        .. versionchanged:: 7.1
+           A CRC32 checksum is appended as a query parameter to local asset
+           URIs (e.g. ``?v=a1b2c3d4``) for cache-busting purposes.
         """
         if loading_method == 'async':
             kwargs['async'] = 'async'
@@ -1527,16 +1554,41 @@ def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> Non
         Example::
 
             app.add_css_file('custom.css')
-            # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
+            # => <link rel="stylesheet" href="_static/custom.css?v=a1b2c3d4"
+            #          type="text/css" />
 
             app.add_css_file('print.css', media='print')
-            # => <link rel="stylesheet" href="_static/print.css"
+            # => <link rel="stylesheet" href="_static/print.css?v=a1b2c3d4"
             #          type="text/css" media="print" />
 
             app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
-            # => <link rel="alternate stylesheet" href="_static/fancy.css"
+            # => <link rel="alternate stylesheet" href="_static/fancy.css?v=a1b2c3d4"
             #          type="text/css" title="fancy" />
 
+        .. note::
+
+           For the file to be included in the output, it must be present in
+           the ``_static`` directory at build time.
+           Extension developers should use :meth:`add_static_dir` to register
+           a directory whose contents will be copied to ``_static``.
+           Site authors can place files into a directory listed in
+           :confval:`html_static_path` instead.
+
+        .. tip::
+
+           Site authors (as opposed to extension developers) who wish to add
+           custom CSS files may find it easier to use the
+           :confval:`html_css_files` configuration value in combination with
+           :confval:`html_static_path`, rather than writing an extension.
+
+        .. note::
+
+           Files registered by extensions can be overridden by site authors
+           by placing a file with the same name into their
+           :confval:`html_static_path`. Note that this may not work in all
+           cases; see `#12096 <https://github.com/sphinx-doc/sphinx/issues/12096>`__
+           for details.
+
         .. list-table:: priority range for CSS files
            :widths: 20,80
 
@@ -1570,6 +1622,10 @@ def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> Non
 
         .. versionchanged:: 3.5
            Take priority argument.  Allow to add a CSS file to the specific page.
+
+        .. versionchanged:: 7.1
+           A CRC32 checksum is appended as a query parameter to local asset
+           URIs (e.g. ``?v=a1b2c3d4``) for cache-busting purposes.
         """
         logger.debug('[app] adding stylesheet: %r', filename)
         self.registry.add_css_files(filename, priority=priority, **kwargs)