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.

  • 2
    possible duplicate of 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
  • 1
    This is very stupid suggestion, but how about tinyurl.com or bit.ly – Mikko Ohtamaa Jan 20 '13 at 2: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 9: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
up vote 7 down vote accepted

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.

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.

Your Answer

 

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.