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

Google Style

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

NumPy Style

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.


Who uses Sphinx?




and more...

Markup language for Sphinx Docs

A brief rundown


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