28

I'm using Sphinxdoc to generate api documentation, and I've run into a problem with pep8 conformance when writing a docstring.

As you can see below, the link to the OWASP site ends at column 105, far past what pep8 dictates 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

    """

Is there a way to wrap the url while still keeping it an url in the generated docs?

Inserting a backslash didn't work.

Nix
  • 57,072
  • 29
  • 149
  • 198
thebjorn
  • 26,297
  • 11
  • 96
  • 138
  • 2
    possible duplicate of [How should I format a long url in a python comment and still be PEP8 compliant](http://stackoverflow.com/questions/10739843/how-should-i-format-a-long-url-in-a-python-comment-and-still-be-pep8-compliant). That one isn't about Sphinx, though. – Lev Levitsky Jan 19 '13 at 13:45
  • 1
    I was hoping shpinx/rst had some way of splitting lines while preserving indentation, especially since the indentation on continuation lines generally is significant. – thebjorn Jan 19 '13 at 16:38
  • 2
    This is very stupid suggestion, but how about tinyurl.com or bit.ly – Mikko Ohtamaa Jan 20 '13 at 02:50
  • 1
    @MikkoOhtamaa tinyurl et.al. is certainly an idea that comes to mind, but I tend to use those services only when I need to communicate an url verbally. Many people don't like these kinds of anonymous links, and I know that some employers block these services, so I don't feel it's appropriate here. I can live with the pep8 warning -- although it would have been nice if you could turn those warnings of selectively, like you can with #pylint:disable=... – thebjorn Jan 21 '13 at 09:09
  • I think you can disable PEP-8 warnings or change settings. At least I have set line width to 999 characters in Sublime Text 2 PEP integration. – Mikko Ohtamaa Jan 21 '13 at 12:36
  • @MikkoOhtamaa yes, you can turn off pep8 warnings globally, you just can't do it on an individual line (I would still like to get warnings about other lines that are too long). – thebjorn Jan 22 '13 at 08:13
  • Ah, yes. My favorite feature in jshint. Maybe time to patch pep-8. The code base is very simple :) – Mikko Ohtamaa Jan 22 '13 at 14:51

2 Answers2

16

A backslash \ does the job, but messes up the pretty indentation.

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

    """

The result (the same is for the long line):

>>> 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

Also, PEP8 is a guide, not a law - this seems a (rare) case where it's ok to ignore it.

Emil Ivanov
  • 37,300
  • 12
  • 75
  • 90
9

Looking into a problem, I came up with a(n elegant?) work around solution.

First, here is my docstring:

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

Second, in the rst file, I have this defined:

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

So when ook is documented, the SQLAlchemy_ link works.

Community
  • 1
  • 1
Sardathrion - against SE abuse
  • 17,269
  • 27
  • 101
  • 156