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