Introduce sphinx-lint (#2234)

rtobar · web-flow · commit fe2858759a06 · 2022-12-02T07:48:03.000+01:00
Estos commits agregan sphinx-lint a los varios lugares donde se realizan
chequeos (CI, pre-commit, Makefile). Para asegurar que nuevas versiones
de sphinx-lint que pueden traer nuevos correctores no quiebran nuestros
builds, la versión de sphinx-lint está definida a un valor exacto en vez
de dejarla fluctuar; más tarde un dependabot nos puede avisar cuando
haya una nueva versión ;)

Escribí un poquito de documentación que ojalá sea útil para cuando estos
errores aparezcan, pero no sé si es suficiente.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -32,6 +32,9 @@ jobs:
           diff -Naur TRANSLATORS <(LANG=es python scripts/sort.py < TRANSLATORS)
       - name: Powrap
         run: powrap --check --quiet **/*.po
+      - name: Sphinx lint
+        run: |
+          sphinx-lint */*.po
       - name: Pospell
         run: |
           python scripts/check_spell.py
diff --git a/.overrides/reviewers-guide.rst b/.overrides/reviewers-guide.rst
@@ -48,6 +48,43 @@ Tres razones por las que puede fallar el *build* de Travis:
 
 Para facilitar la comparación de ficheros se emplea este programa que va a hacer que todas las líneas tengan el mismo tamaño. Solucionar este problema en nuestra traducción es muy sencillo, solo hay que instalar la herramienta powrap en nuestro entorno y ejecutar el comando ``powrap nuestro_fichero.po``
 
+``sphinx-lint`` falla
+---------------------
+
+El formato en el que la documentación de python está escrito
+(`reStructredText <https://es.wikipedia.org/wiki/ReStructuredText>`_ , o rst)
+puede ser difícil de manejar y escribir correctamente.
+``sphinx-lint`` ayuda a encontrar errores comunes al momento de escribir
+entradas en este formato, y advierte al respecto.
+
+Entre los errores más comunes están:
+
+* Textos literales no están separados por un espacio
+  respecto a las palabras que lo rodean:
+
+  * Mal: :literal:`no hay espacio antes del\`\`literal\`\``
+  * Mal: :literal:`después del \`\`literal \`\`no hay un espacio`
+  * Bien: :literal:`hay espacio antes del \`\`literal\`\` y después también`
+
+* Textos literales comienzan o terminan con espacios:
+
+  * Mal: :literal:`\`\` literal empieza con un espacio\`\``
+  * Mal: :literal:`\`\`literal termina con un espacio \`\``
+  * Bien: :literal:`\`\`literal no termina ni empieza con espacios\`\``
+
+* Textos literales no están delineados con dos acentos fuertes:
+
+  * Mal: :literal:`\`\`falta uno al final :(\``
+  * Mal: :literal:`\`falta uno al principio :(\`\``
+  * Bien: :literal:`\`\`todo bien :)\`\``
+
+* Enlaces no terminan en un guión bajo:
+
+  * Mal: :literal:`\`<https://python.org>\``
+  * Mal: :literal:`\`Python <https://python.org>\``
+  * Bien: :literal:`\`<https://python.org>\`_`
+  * Bien: :literal:`\`Python <https://python.org>\`_`
+
 
 ``pospell`` falla
 ---------------------
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -11,3 +11,9 @@ repos:
         language: python
         additional_dependencies: ['pospell>=1.1']
         files: \.po$
+    -   id: lint
+        name: Run sphinx linting
+        entry: sphinx-lint
+        language: python
+        additional_dependencies: ['sphinx-lint==0.6.7']
+        files: \.po$
diff --git a/Makefile b/Makefile
@@ -99,6 +99,10 @@ progress: venv
 spell: venv
 	$(VENV)/bin/python scripts/check_spell.py
 
+.PHONY: lint
+lint: venv
+	$(VENV)/bin/python -m sphinxlint */*.po
+
 
 .PHONY: wrap
 wrap: venv
diff --git a/glossary.po b/glossary.po
@@ -1705,7 +1705,7 @@ msgid ""
 msgstr ""
 "En entornos multi-hilos, el método LBYL tiene el riesgo de introducir "
 "condiciones de carrera entre los hilos que están \"mirando\" y los que están "
-"\"saltando\".  Por ejemplo, el código, `if key in mapping: return "
+"\"saltando\".  Por ejemplo, el código, ``if key in mapping: return "
 "mapping[key]``  puede fallar si otro hilo remueve *key* de *mapping* después "
 "del test, pero antes de retornar el valor.  Este problema puede ser resuelto "
 "usando bloqueos o empleando el método EAFP."
@@ -2469,7 +2469,7 @@ msgid ""
 msgstr ""
 "Cuando es usado para referirse a los módulos, *nombre completamente "
 "calificado* significa la ruta con puntos completo al módulo, incluyendo "
-"cualquier paquete padre, por ejemplo, `email.mime.text``::"
+"cualquier paquete padre, por ejemplo, ``email.mime.text``::"
 
 #: ../Doc/glossary.rst:1063
 msgid "reference count"
diff --git a/library/platform.po b/library/platform.po
@@ -375,9 +375,9 @@ msgid ""
 "to ``'Enterprise'``, ``'IoTUAP'``, ``'ServerStandard'``, and "
 "``'nanoserver'``."
 msgstr ""
-"Retorna una cadena que representa la edición actual de Windows o ``None``si "
+"Retorna una cadena que representa la edición actual de Windows o ``None`` si "
 "el valor no puede ser determinado. Los valores posibles incluyen, entre "
-"otros, ``'Enterprise'``, ``'IoTUAP'``, ``'ServerStandard'`` y "
+"otros, ``'Enterprise'``, ``'IoTUAP'``, ``'ServerStandard'``  y "
 "``'nanoserver'``."
 
 #: ../Doc/library/platform.rst:224
diff --git a/library/queue.po b/library/queue.po
@@ -391,8 +391,8 @@ msgid ""
 "or :mod:`weakref` callbacks."
 msgstr ""
 "Este método tiene una implementación en C la cual ha sido usada "
-"anteriormente. Los llamados ``put()`` o ``get()``pueden ser interrumpidos "
-"por otro llamado ``put()``en el mismo hilo sin bloquear o corrompoer el "
+"anteriormente. Los llamados ``put()`` o ``get()`` pueden ser interrumpidos "
+"por otro llamado ``put()`` en el mismo hilo sin bloquear o corromper el "
 "estado interno dentro de la fila. Esto lo hace apropiado para su uso en "
 "destructores como los métodos ``__del__`` o las retrollamadas :mod:`weakref`."
 
diff --git a/requirements.txt b/requirements.txt
@@ -13,4 +13,5 @@ pre-commit
 sphinx-autorun
 sphinxemoji
 sphinx-tabs
+sphinx-lint==0.6.7
 tabulate
diff --git a/whatsnew/2.5.po b/whatsnew/2.5.po
@@ -1468,7 +1468,7 @@ msgstr ""
 "hasta ``2**31 - 1`` = 2147483647 elementos. (En realidad, hay algunos "
 "modelos de programación diferentes que los compiladores de C de 64 bits "
 "pueden usar; consulte https://unix.org/version2/whatsnew/lp64_wp.html para "
-"ver una discusión, pero el modelo más comúnmente disponible deja :c: expr:"
+"ver una discusión, pero el modelo más comúnmente disponible deja :c:expr:"
 "`int` como 32 bits)."
 
 #: ../Doc/whatsnew/2.5.rst:888
