Menu
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.
210
As mentioned above, Python docstrings are strings used right after the definition of a function, method, class, or module (like in Example 1). They are used to document our code. We can access these docstrings using the __doc__ attribute.
A Python docstring is a string used to document a Python module, class, function or method, so programmers can understand what it does without having to read the details of the implementation. Also, it is a common practice to generate online (html) documentation automatically from docstrings.
Every function you create ought to have a docstring. They're in triple-quoted strings and allow for multi-line text.
Declaring Docstrings: The docstrings are declared using ”'triple single quotes”' or “””triple double quotes””” just below the class, method or function declaration. All functions should have a docstring.
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.
126
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
