sphinx-doc/sphinx

Incomplete documentation for add_js_file() and add_css_file()

Open

#12,223 opened on 2024年4月2日

GitHub で見る
 (3 comments) (2 reactions) (0 assignees)Python (5,625 stars) (1,985 forks)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
Issue 種別
documentation
難度新しい貢献者にとっての実装難度です。1 は非常に小さな変更、5 は専門的な作業です。
2
推定時間経験ある貢献者が調査、実装、テスト、pull request 準備にかけるおおよその時間範囲です。
1-3 hours
活動状況Issue が今どれだけ取り組みやすいかを示します。新しい、活発、古い、ブロック中、またはメンテナー入力待ちなどです。
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.