如何打破第一个文档字符串中的链接以满足 pep8？答案

【问题标题】：How do I break a link in a rst docstring to satisfy pep8?如何打破第一个文档字符串中的链接以满足 pep8？
【发布时间】：2013-01-03 02:31:26
【问题描述】：

我正在使用 Sphinxdoc 生成 api 文档，并且在编写文档字符串时遇到了 pep8 一致性问题。

如下所示，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？

插入反斜杠不起作用。

【问题讨论】：

How should I format a long url in a python comment and still be PEP8 compliant 的可能副本。不过，那不是关于狮身人面像的。
我希望 shpinx/rst 在保留缩进的同时有一些分割线的方法，特别是因为续行上的缩进通常很重要。
这是一个非常愚蠢的建议，但是 tinyurl.com 或 bit.ly 怎么样
@MikkoOhtamaa tinyurl 等。肯定是我想到的一个想法，但我倾向于仅在需要口头交流 url 时才使用这些服务。很多人不喜欢这种匿名链接，而且我知道有些雇主会屏蔽这些服务，所以我觉得这里不合适。我可以忍受 pep8 警告——尽管如果你可以选择性地关闭这些警告会很好，就像你可以使用 #pylint:disable=...
我认为您可以禁用 PEP-8 警告或更改设置。至少我在 Sublime Text 2 PEP 集成中将线宽设置为 999 个字符。

标签： python python-sphinx restructuredtext pep8

【解决方案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】：

查看a problem，我想出了一个（优雅的？）解决方案。

首先，这是我的文档字符串：

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

其次，在第一个文件中，我定义了这个：

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

因此，当 ook 被记录时，SQLAlchemy_ 链接有效。

【讨论】：

链接已损坏。