Skip to content

The Documentation System#

We're using MKdocs with various plugins so everything is auto-generated from docstrings inside the code. We use Google docstring style 4 in python code.

Take a look at the source codes for this file and this other file for examples of how that looks like in the code.

Cross references are made with full qualified object names 5. Click the "Edit" button at the top of the page to see how that looks like.

Linking to GitHub can also be done: #66, hoover-search#66, CRJI/EIC#666, node#66 (for cross-provider URLs). These are auto-linked with no markdown needed. Getting a link is avoided by using backticks: #66.

Issues and their work-arounds#

  1. There's no way to disable alphabetical sorting in preference of code order sorting 101112.
  2. There's no way to control capitalization in MkDocs 1 so we added our own CSS to make everything lowercase on the left side of the screen.
  3. For Django Rest Framework, deactivating some parts of the internal field parser of mkdocstrings is required 2.
  4. There is no out-of-the-box configuration for mocking out modules (like Sphinx has 3) so we had to roll our own. The full path of the mocked object must be provided, not only just top modules - maybe we could install Sphinx and use its code for mocking?
  5. Complete inheritance tree must be accessible for a class to show up in the docs. So we can't mock out Django, rest_framework, or any other library that we base our Classes from, or that we use at the top level (import level).
  6. The footnotes don't work well with titles 6.
  7. The footnotes don't renumber themselves in the correct order 7.
  8. Since we use separate requirements files for building docs (to ease setting up the build process for readthedocs), the versions for the various libraries that we do install (only django and rest_framework and their dependencies) will be out of sync from the main code repository.
  9. There's a bug that displays parent docstring in inherited fields 8. You can work around this by supplying docstrings everywhere.
  10. All decorators must use functools.wraps 9. If a decorator does not use this, the decorated function will not appear in the documentation. For our decorators, this is a simple fix; for Library decorators (like the ones generated by Celery) they must be mocked out if they don't use functools.wraps.
  11. There are two warnings that we would want to silence, since they're not problems related to the docs and make it harder to keep an eye on the errors:
    • Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests ... -- we're running this with docker, so we must bind to all interfaces
    • WARNING - Overwriting existing registered function lunr-multi-trimmer-en -- happens when we enable search prebuilt_index with the python runner.

  1. github.com/mkdocs/mkdocs/issues/1289#issuecomment-331021585 ↩

  2. mkdocstrings/mkdocstrings#141 ↩

  3. www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports ↩

  4. google.github.io/styleguide/pyguide.html ↩

  5. mkdocstrings.github.io/usage/#cross-references ↩

  6. Python-Markdown/markdown#660 ↩

  7. Python-Markdown/markdown#1117 ↩

  8. mkdocstrings/pytkdocs#47 ↩

  9. mkdocstrings.github.io/troubleshooting/#my-wrapped-function-shows-documentationcode-for-its-wrapper-instead-of-its-own ↩

  10. mkdocstrings/mkdocstrings#114 ↩

  11. mkdocstrings/pytkdocs#29 ↩

  12. mkdocstrings/mkdocstrings#102 ↩