sphinx-doc/sphinx

Incomplete documentation for add_js_file() and add_css_file()

Open

#12,223 建立於 2024年4月2日

在 GitHub 查看
 (3 留言) (2 反應) (0 負責人)Python (5,625 star) (1,985 fork)batch import
easygood first issuehelp wantedsprinttype:bugtype:docs

描述

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.

貢獻者指南

技術棧
python
領域
documentation
議題類型
documentation
難度面向新貢獻者的預計實作難度，1 表示很小改動，5 表示專家級工作。
2
預計時間有經驗貢獻者完成調查、實作、測試並準備 pull request 的粗略時間範圍。
1-3 hours
活動狀態議題目前的可參與程度：新鮮、活躍、陳舊、阻塞或等待維護者輸入。
fresh
清晰度議題是否清楚說明預期改動、驗收標準和下一步。
clear
前置要求
Understanding of Sphinx APIFamiliarity with versionchanged directivesBasic Python
新手友善度1-100 的估計分數，表示該議題對首次貢獻者的友善程度。
70
研究方向
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.