24

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

正如您在下面看到的，到 OWASP 站点的链接在第 105 列结束，远远超过 pep8 规定的最大行长

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 同时仍将其保留在生成的文档中？

插入反斜杠不起作用。

4

2 回答 2

13

反斜杠\可以完成这项工作，但会破坏漂亮的缩进。

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

于 2013-01-19T13:43:42.160 回答
8

调查一个问题，我想出了一个（优雅的？）解决方案。

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

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

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

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

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

于 2015-02-25T13:37:15.813 回答