sphinx-doc/sphinx

Incomplete documentation for add_js_file() and add_css_file()

Open

#12 223 ouverte le 2 avr. 2024

Voir sur GitHub
 (3 commentaires) (2 réactions) (0 assignés)Python (1 985 forks)batch import
awaiting:revieweasygood first issuehelp wantedsprinttype:bugtype:docs

Métriques du dépôt

Stars
 (5 625 stars)
Métriques de merge PR
 (Merge moyen 13j 10h) (8 PRs mergées en 30 j)

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.

Guide contributeur

Direction de recherche
Examinez les docstrings pour add js file et add css file dans sphinx/application.py, ainsi que la documentation générée aux URL fournies. Ajoutez des exemples de somme de contrôle CRC32 comme indiqué dans l'issue liée #11415. Insérez une directive 'versionchanged' pour la version 7.1. Envisagez d'ajouter une note sur la copie des fichiers vers static et l'utilisation des valeurs de configuration html js files/html css files pour les auteurs du site, en référençant leur documentation.
Stack technique
python
Domaine
documentation
Type d'issue
Documentation
DifficultéDifficulté estimée pour un nouveau contributeur, de 1 pour un très petit changement à 5 pour un travail expert.
2
Temps estiméFourchette de temps approximative pour investiguer, implémenter, tester et préparer une pull request.
1-3 heures
Statut d'activitéDisponibilité apparente de l'issue : fraîche, active, ancienne, bloquée ou en attente d'un mainteneur.
Récente
ClartéClarté avec laquelle l'issue explique le changement attendu, les critères d'acceptation et la prochaine étape.
Claire
Prérequis
Understanding of Sphinx APIFamiliarity with versionchanged directivesBasic Python
Accessibilité débutantScore de 1 à 100 estimant l'accessibilité de cette issue pour un premier contributeur.
70