ejemplo - restructuredtext python

¿Cómo rompo un enlace en una primera cadena de documentos para satisfacer pep8?

Question

Estoy usando Sphinxdoc para generar la documentación de la API, y me he encontrado con un problema de conformidad con pep8 al escribir una cadena de documentos.

Como puede ver a continuación, el enlace al sitio de OWASP termina en la columna 105, mucho más allá de lo que pep8 dicta la maximum-line-length

def handle_csrf(...):
"""The general recommendation by people in the know [OWASP]_, is
''to implement the Synchronizer Token Pattern (STP_)''.
.. [OWASP] The Open Web Application Security Project
(https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet)
.. _STP: http://www.corej2eepatterns.com/Design/PresoDesign.htm
"""

¿Hay una manera de envolver la url mientras se mantiene una url en los documentos generados?

Insertar una barra invertida no funcionó.

Answer 1

Al buscar un problema , se me ocurrió una solución alternativa (¿elegante?).

Primero, aquí está mi docstring:

def ook():
"""The sound a monkey makes...
⚠ `SQLAlchemy`_ used here.
"""
...

Segundo, en el primer archivo, tengo esto definido:

.. autofunction:: ook
.. _SQLAlchemy: http://www.sqlalchemy.org

Así que cuando se documenta ook , el enlace SQLAlchemy _ funciona.

Answer 2

Una barra invertida / hace el trabajo, pero desordena la sangría bonita.

def handle_csrf():
"""The general recommendation by people in the know [OWASP]_, is
''to implement the Synchronizer Token Pattern (STP_)''.
.. [OWASP] The Open Web Application Security Project
(https://www.owasp.org/index.php/Cross-/
Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet)
.. _STP: http://www.corej2eepatterns.com/Design/PresoDesign.htm
"""

El resultado (lo mismo es para la línea larga):

>>> print handle_csrf.__doc__
The general recommendation by people in the know [OWASP]_, is
''to implement the Synchronizer Token Pattern (STP_)''.
.. [OWASP] The Open Web Application Security Project
(https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet)
.. _STP: http://www.corej2eepatterns.com/Design/PresoDesign.htm

Además, PEP8 es una guía, no una ley; parece un caso (raro) en el que está bien ignorarlo.