sphinx-doc/sphinx

Incomplete documentation for add_js_file() and add_css_file()

Open

#12,223 opened on Apr 2, 2024

View on GitHub
 (3 comments) (2 reactions) (0 assignees)Python (5,625 stars) (1,985 forks)batch import
easygood first issuehelp wantedsprinttype:bugtype:docs

Description

Describe the bug

  • The examples do not include the CRC32 checksums added in #11415
  • There should be a "changed in version 7.1" mentioning those checksums (https://www.sphinx-doc.org/en/master/changes.html#release-7-1-0-released-jul-24-2023)
  • There should be a hint how JS/CSS files can be copied to the _static directory (see also https://github.com/sphinx-doc/sphinx/issues/11173#issuecomment-1496483665)
  • It might also be helpful to mention that site authors (as opposed to extension developers) can use the config values html_js_files and html_css_files in combination with html_static_path?
  • Maybe it could even be mentioned that files specified by extensions can be overridden by site authors by simply putting a file with the same name into their html_static_path (which currently doesn't fully work: #12096)?

How to Reproduce

Look at https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_js_file and https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_css_file.

Contributor guide

Tech stack
python
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Understanding of Sphinx APIFamiliarity with versionchanged directivesBasic Python
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
Examine the docstrings for add js file and add css file in sphinx/application.py, as well as the generated documentation at the provided URLs. Add CRC32 checksum examples as shown in the linked issue #11415. Insert a 'versionchanged' directive for 7.1. Consider adding a note about copying files to static and the use of html js files/html css files config values for site authors, referencing their documentation.