Sphinx
And
Read the Docs
Presenter: Rigel Trajano
Outline
- Python Doc Strings
-
Various Docstring Styles
- Sphinx
- Read the Docs
What is a Docstring?
A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object. --PEP257
What is a Docstring?
class Greeter():
def __init__(self, msg, name):
self.msg = msg
self.name = name
def greet(self):
print('{}, {}!'.format(self.msg, self.name))
"""MODULE DOCSTRING -- An example module.""" class Greeter(): """CLASS DOCSTRING -- A class that greets."""
def __init__(self, msg, name): """METHOD DOCSTRING -- Init Function."""
self.msg = msg
self.name = name
def greet(self): """METHOD DOCSTRING -- Greeter method."""
print('{}, {}!'.format(self.msg, self.name))
What is a Docstring?
>>> help(Greeter) Help on class Greeter in module __main__:
class Greeter(builtins.object)
| CLASS DOCSTRING -- A class that greets.
|
| Methods defined here:
|
| __init__(self, msg, name)
| METHOD DOCSTRING -- Init Function.
|
| greet(self)
| METHOD DOCSTRING -- Greeter method.
|
>>> my_greeter = Greeter('Hello', 'Spiderman')
>>> help(my_greeter.greet)
Help on method greet in module __main__:
greet(self) method of __main__.Greeter instance
METHOD DOCSTRING -- Greeter method.
>>> print(repr(my_greeter.greet.__doc__))
'METHOD DOCSTRING -- Greeter method.'
What is a Docstring?
For consistency, always use """triple double quotes""" around docstrings. Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""". --PEP257
PEP8 Multiline Docstring convention
def foo(): """FUNCTION DOCSTRING SUMMARY -- Does some foo magic.
the quotes of a multiline docstring should be on a line by itself.
.. Example::
>>> print('this is a doctest')
this is a doctest
""" pass
Docstring styles
def example_generator(n):
"""Generators have a ``Yields`` section instead of a ``Returns`` section.
Args:
n (int): The upper limit of the range to generate, from 0 to `n` - 1
Yields:
int: The next number in the range of 0 to `n` - 1
Examples:
Examples should be written in doctest format, and should
illustrate how to use the function.
>>> print [i for i in example_generator(4)]
[0, 1, 2, 3]
"""
for i in range(n):
yield i
Docstring Styles
def example_generator(n):
"""Generators have a ``Yields`` section instead of a ``Returns`` section.
Parameters
----------
n : int
The upper limit of the range to generate, from 0 to `n` - 1
Yields
------
int
The next number in the range of 0 to `n` - 1
Examples
--------
Examples should be written in doctest format, and should illustrate
how to use the function.
>>> print [i for i in example_generator(4)]
[0, 1, 2, 3]
"""
for i in range(n):
yield i
Docstring styles
Sphinx Style
def public_fn_with_sphinxy_docstring(name, state=None):
"""This function does something.
:param name: The name to use.
:type name: str.
:param state: Current state to be in.
:type state: bool.
:returns: the return code.
:rtype: int.
:raises: AttributeError, KeyError
"""
return 0
Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.
Markup language for Sphinx Docs
Read the Docs hosts documentation, making it fully searchable and easy to find.
Let's Code! |
---|
References
Sphinx and Read the Docs
By Rigel Trajano
Sphinx and Read the Docs
- 1,686