24

Sphinxdocを使用してAPIドキュメントを生成していますが、docstringを作成するときにpep8準拠の問題が発生しました。

以下に示すように、OWASPサイトへのリンクは、pep8が最大行長を指示するものをはるかに超えた列105で終了します。

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をラップする方法はありますか？

バックスラッシュの挿入は機能しませんでした。

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

問題を調べて、私は（nエレガント？）回避策を思いついた。

まず、これが私のdocstringです：

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 に答える