Documentation
Thoughts
Craig Loftus
Sphinx
De facto option for documentation in Python
Documentation for it is ironically terrible
autodoc
Pulls in your docstrings
.. automodule:: oscar.model.fields
:members:
.. automodule:: oscar.model.fields
:members:
:exclude-members: contribute_to_class, to_python
A mistake?
"Complete" principle from Write The Docs suggests autodoc is risky.
Spelling
sphinxcontrib.spelling
wraps pyenchant
which wraps enchant
which wraps spell checkers (e.g. aspell)
Wordlists
Should they be a thing?
callables bugfix committer
misconfiguration onwards unharmful
spam screenshot outbox
.. spelling ::
Django
Wagtail
docs/spelling_wordlist
autodoc
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
Roles
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:
Linking
Too fussy?
def process_docstring(app, what, name, obj, options, lines):
# do things
Add roles automatically
Document Django model fields
Too magic?
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>`
"""
Intersphinx
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)
}
When to do it?
Comments?
Documentation
By Craig Loftus
Documentation
- 1,088