If you're using sphinx to generate your documentation
"""
`here <url>`__
"""
in your docstrings should be parsed properly.
Answer from Azaria Gebremichael on Stack OverflowIf you're using sphinx to generate your documentation
"""
`here <url>`__
"""
in your docstrings should be parsed properly.
Just add the link as a string into the docstring, like so:
def foo():
"""Lorem ipsum for more info, see here: www.myfancydocu.com""
The doctring is just a string, so there is no Hyperlink. But anyone that wants to look at the website can just copy the link.
There are automatic documentation-builders that build a documentation out of your code and docstrings in e.g. html. Those can probably add hyperlinks to the documentation with a specific syntax, but that syntax then depends on which documentation-builder you use. If you only have your code, then just adding the url as a string is all you can do.
The solution that works for Sphinx is to prefix the reference with ~.
Per the Sphinx documentation on Cross-referencing Syntax,
If you prefix the content with
~, the link text will only be the last component of the target. For example,:py:meth:`~Queue.Queue.get`will refer toQueue.Queue.getbut only displaygetas the link text.
So the answer is:
class MyClass():
def foo(self):
print 'foo'
def bar(self):
"""This method does the same as :func:`~mymodule.MyClass.foo`"""
print 'foo'
This results in an HTML looking like this : This method does the same as foo(), and foo() is a link.
However, note that this may not display in Spyder as a link.
If you want to manually specify the text of the link you can use:
:func:`my text <mymodule.MyClass.foo>`
For more information, checkout Cross-referencing Python objects.
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.
Don't break the url:
Some other good reasons to ignore a particular guideline:
- When applying the guideline would make the code less readable, even for someone who is used to reading code that follows this PEP. ...
Source:
# A Foolish Consistency is the Hobgoblin of Little Minds [1]
# [1]: http://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds
You can use the # noqa at the end of the line to stop PEP8/pycodestyle/Flake8 from running that check. Should also avoid warnings in your IDE.
# [1]: http://www.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds # noqa
From PEP8
But most importantly: know when to be inconsistent -- sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!
Two good reasons to break a particular rule:
- When applying the rule would make the code less readable, even for someone who is used to reading code that follows the rules.
Personally, I would use that advice, and rather leave the full descriptive URL in your comment for people.
I contacted support and it turns out it hasn't been implemented.
I have created a feature request on their issue tracker:
https://youtrack.jetbrains.com/issue/PY-14743
Update:
original feature request is marked as a duplicate of
https://youtrack.jetbrains.com/issue/PY-27635
State: In progress
def die_hard(self):
"""
Throws a :class:`NakatomiPlazaError`.
"""
raise NakatomiPlazaError('Yippee ki-yay')
Worked for me.