Craig Loftus
De facto option for documentation in Python
Documentation for it is ironically terrible
Pulls in your docstrings
.. automodule:: oscar.model.fields :members:
.. automodule:: oscar.model.fields :members: :exclude-members: contribute_to_class, to_python
"Complete" principle from Write The Docs suggests autodoc is risky.
sphinxcontrib.spelling
wraps pyenchant
which wraps enchant
which wraps spell checkers (e.g. aspell)
Should they be a thing?
callables bugfix committer
misconfiguration onwards unharmful
spam screenshot outbox
.. spelling :: Django Wagtail
docs/spelling_wordlist
Can make tracking down 'mistakes' tricky
Inherited docstrings from third party packages
will cause you headaches.
The answer is to document your overridden methods,
but that can feel redundant
You give semantic meaning with roles
class Foo: """ Foo likes :py:class:`project.models.Bar` """
:py:mod:
:py:func:
:py:data:
:py:const:
:py:class:
:py:meth:
:py:attr:
:py:exc:
:py:obj:
def process_docstring(app, what, name, obj, options, lines): # do things
Add roles automatically
Document Django model fields
Done manually you can massage the role definitions
to improve readability.
class Cat: """ Cat likes :py:class:`~project.models.Milk` """ class Dog: """ Dog likes :py:class:`Food <project.models.AbstractFood>` """
Not limited to linking within your own project.
Particularly useful if your project leverages a framework
intersphinx_mapping = { 'python': ('https://docs.python.org/3', None) }
By Craig Loftus
