Как я могу сломать ссылку в первой docstring, чтобы удовлетворить pep8?

Я использую Sphinxdoc для создания документации api, и я столкнулся с проблемой соответствия pep8 при написании docstring.

Как вы можете видеть ниже, ссылка на сайт OWASP заканчивается в столбце 105, далеко от того, что pep8 диктует 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

    """

Есть ли способ обернуть URL-адрес, сохранив при этом его url в сгенерированных документах?

Вставка обратной косой черты не работает.

Ответ 1

Обратная косая черта \ выполняет задание, но испортит красивый отступ.

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

    """

Результат (то же самое для длинной строки):

>>> 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

Кроме того, PEP8 - это руководство, а не закон. Это кажется редким случаем, когда он игнорирует его.

Ответ 2

Заглянув в проблему, я придумал (n элегантный?) решение.

Во-первых, вот моя docstring:

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

Во-вторых, в первом файле я определил это:

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

Итак, когда ook документировано, работает ссылка SQLAlchemy _.