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

  • 114
Loading comments...

More from Craig Loftus