Как я могу сломать ссылку в первой 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 _.
