mdk
/
talks
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
talks/2023-pycon-fr-sphinx-lint.md

5.8 KiB
Raw Blame History

sphinx-lint

Un linter pour ta doc.


Julien Palard

CPython core dev
Sysadmin de l’AFPy
hackinscience.org
…

Pourquoi ?

Trouver des fautes de frappe dans du rst, ni plus, ni moins.

Depuis quand ?

Author: Georg Brandl <georg@python.org>
Date:   Sat Jan 3 20:30:15 2009 +0000

Dans cpython dans Doc/tools/rstlint.py !

::: notes

Oui oui, Georg, l'auteur de Sphinx-doc.

Depuis quand, quoi ?

Et dans cpython on en avait un autre, make suspicious.

Bien connu pour ses faux positifs.

::: notes

Lui il date du portage de la doc de LaTeX à Sphinx, 2009 aussi.

La motivation

Remplacer make suspicious par un outil qui n’aurait aucun faux positif.

::: notes

Et qui serait rapide !

Parler de la lenteur de make suspicious.

La motivation

Sortir l’outil de cpython/Doc/tools pour que tout le monde puisse l'utiliser.

Parsons du rst !

Le reStructuredText

Le balisage :

*En italique*
**En gras**
`Interprété` (dont le rôle peut changer)
``litéral``
Lien_
`Autre lien`_
`Encore un lien <https://...>`_
`Un lien anonyme <https://...>`__

Le reStructuredText

Les textes interprétés :

`while`  C'est du texte interprété.
:keyword:`while`  Du texte interprété avec un « role marker »
`while`:keyword:  Ça lui donne un sens particulier.

Le reStructuredText

Donc oui le balisage et le texte interprété peuvent jouer le même rôle :

*ça* c'est pareil que :emphasis:`ça`.
**ça** c'est pareil que :strong:`ça`.
``ça`` c'est pareil que :literal:`ça`.

::: notes

Mais comme en Python on a plus de méthodes que d'opérateurs…

En rst on a plus de rôles que de balises !

Le reStructuredText

Les directives :

 .. image:: Lenna.jpg

 .. important::
    Elle s’appelle Lena Sjööblom.

::: notes

Je prends un gros raccourci : les directives ne sont qu'un bout de tout le balisage "explicite" comme les commentaires, les notes de bas de page, ...

Parsons du rst !

C'est facile ! Ou pas…

Exemple, comment on interprète :

*2 * x  *a **b *.txt*

::: notes

C'est tout en italique !

Parsons du rst !

Vous voyez des balises, vous ?

2 * x ** 2 + 3 * x ** 3

a || b

"*" '|' (*) [*] {*} <*> ‘*’

2*x a**b O(N**2) e**(x*y)

::: notes

Pas le parseur. Mais bon les règles sont bien documentées ♥

Mais on voit que les humains peuvent facilement faire des erreurs ici.

Parsons du rst !

Regardons du côté des directives :

.. code-block:: python

   def fib(x):
       if n in (0, 1):
           return 1
       x = n // 2
       return fib(x - 1) * fib(n - x - 1) + fib(x) * fib(n - x)

::: notes

Une directive peut avoir un corps, ici du code.

Parsons du rst !

Regardons du côté des directives :

.. image:: Lenna.jpg
   :height: 330px
   :width: 330px
   :scale: 50 %
   :alt: Lenna Sjööblom

::: notes

Une directive peut avoir des options mais pas de corps.

Parsons du rst !

Regardons du côté des directives :

.. csv-table:: Domaines d'organismes publics
   :header: "name", "http_status", "https_status"
   :widths: 20, 10, 10

   cgf.pf, 200, 200
   dun.fr, 200, 200
   caf.pf, 200, 200
   aze.fr, 200, 200

::: notes

Une directive peut avoir des options et un corps.

Quiz !

.. code-block:: python

   items = ["titi", "tata", "toto"]
   print(*items)


.. important::

   items = ["titi", "tata", "toto"]
   print(*items)

Quiz !

.. csv-table:: Domaines d'organismes publics
   :header: "name", "http_status", "https_status"
   :widths: 20, 10, 10

   cgf.pf, 200, 200, OK
   dun.fr, 200, 200, OK

.. csv-table:: Domaines d'organismes publics
   :header: "name", "http_status", "https_status"
   :widths: 20, 10, 10

   caf.pf
   aze.fr

::: notes

Les valeurs manquantes sont moins graves que les valeurs surnuméraires.

Ne parsons pas de rst...

De toutes façons sphinx-lint ne cherche pas du rst valide, il cherche du rst invalide !

C’est utilisé ?

  • CPython (depuis longtemps), devguide, peps, traductions, ...
  • neo4j-python-driver
  • pandas
  • Spyder IDE
  • Sympy
  • Sphinx !!!

Ça trouve des bugs ?

Dans les PEPS

-`vcs <https://pythonhosted.org/vcs/>` library as
+`vcs <https://pythonhosted.org/vcs/>`_ library as

Dans sympy

-... autoclass:: sympy.assumptions.predicates.order
+.. autoclass:: sympy.assumptions.predicates.order

-:data:``sympy.parsing.sympy_parser.transformations``
+:data:`sympy.parsing.sympy_parser.transformations`

-  `KanesMethod`` objects.
+  ``KanesMethod`` objects.

Dans la traduction

I just run the tool against library/ as a whole and it spit out a loooot of messages, so I thought that maybe it didn't work with our po files.

Dans la traduction

After closer inspecting two of these files I found that they were indeed proper errors

-"datetime`. :const:`MINYEAR` es` `1``."
+"datetime`. :const:`MINYEAR` es ``1``."

... notes

Ils ont réparé plus de 300 erreurs !

Et les faux positifs ?

Ils se cachent bien :

  • Aucun dans la doc de Sphinx, c’est un bon test (beaucoup de rst dans du rst).
  • Aucun dans la doc de Python, c’est un bon test (286k lignes de rst).

OK, vendu !

Mais comment ça s’utilise ?

$ python -m pip install sphinx-lint
$ sphinx-lint

Bouh c’est pas packagé pour [distrib]

Bah, fais-le.

Questions ?