Question

我正在使用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

    """

有没有办法包装网址，同时仍然在生成的文档中保留网址？

插入反斜杠不起作用。

Answer 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是一个指南，而不是一个法律 - 这似乎是一个（罕见的）可以忽略它的情况。

Answer 2

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

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

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

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

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

因此，当记录ook时，SQLAlchemy _链接有效。

如何在第一个文档字符串中断链接以满足pep8？

2 个答案: