Documenting models and fields

Using Django
1

Is there a standard way to document Django models and their fields?

The documentation says something about documentation in the admin but I’d like to have extracted pages that anybody can read.

What I could Google about this did not seem very clear. Are there any tickets to improve this?

1 Like
2

We use this contrib app.

I think in our case, we can make html from this there is a batch file in docs and you just type ‘make html’, I think this is it. https://docutils.sourceforge.io/docs/user/html.html

They get put in a folder called _build. But we need to get this up to date.

3

What does that mean do we need to adjust this?

4

Well, I don’t know much about your situation, and tbh it is possible we just have two independent solutions.

I believe if you step through the ‘admindocs’ app setup you get some auto-generated documentation derived from the docstrings in your code, served at admin/docs/.

We also have ‘sphinx’ set up to generate docs from .rst files and docstrings, and it generates static HTML pages with a read-the-docs theme (styles etc), which we can move to a static file server upstream. This sounds more like what you want.

Maybe someone else can give clarity on the overlap, if any, between the two solutions. I jumped to a conclusion that our admindocs and sphinx docs were working together and I don’t think it was warranted.

5

I’ll have to try this. Team said they couldn’t get it to work so now they have a weird script in place.

6

I’m using Sphinx and that seems to be quite broken:

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/Users/alpercugun-gscheidel/.pyenv/versions/3.7.8/lib/python3.7/site-packages/sphinx/config.py", line 319, in eval_config_file
    execfile_(filename, namespace)
  File "/Users/alpercugun-gscheidel/.pyenv/versions/3.7.8/lib/python3.7/site-packages/sphinx/util/pycompat.py", line 89, in execfile_
    exec(code, _globals)
  File "/Users/alpercugun-gscheidel/work/workbench/nsm_workbench/docs/conf.py", line 22, in <module>
    django.setup()
  File "/Users/alpercugun-gscheidel/.pyenv/versions/3.7.8/lib/python3.7/site-packages/django/__init__.py", line 24, in setup
    apps.populate(settings.INSTALLED_APPS)
  File "/Users/alpercugun-gscheidel/.pyenv/versions/3.7.8/lib/python3.7/site-packages/django/apps/registry.py", line 91, in populate
    app_config = AppConfig.create(entry)
  File "/Users/alpercugun-gscheidel/.pyenv/versions/3.7.8/lib/python3.7/site-packages/django/apps/config.py", line 90, in create
    module = import_module(entry)
  File "/Users/alpercugun-gscheidel/.pyenv/versions/3.7.8/lib/python3.7/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 965, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'rest_framework'

The whole Sphinx workflow is fully absurd:

  • Using RST
  • Having a separate conf.py file that seems broken
  • Extracting the docs into RST first?

Like: I have a folder with python files in it. Each file contains documentation. Why not just extract that and generate something from that?

Why make things so ridiculously complicated for no reason?

7

I think what I want to have may likely be something like: https://pdoc3.github.io/pdoc/

8

Pdoc3 also doesn’t work because it gets tangled up with django.

9

My experience with Sphinx and Django is that the Sphinx conf.py needs to be updated to call Django’s setup function if you have any autodoc directives in your ReStructuredText files. It’s a bit painful, but it can be done.

10

Yeah, the setup() is literally in there. It’s just not finding all the imports of the django project itself for some strange reason.

11

Maybe you need to adjust the sys.path. Here’s an example from one of my projects where I add the directory above the docs directory so I can can import a version number.

import sys
import os

sys.path.append(os.path.abspath('..'))
from tap import __version__

It does seem weird that it can’t find third party stuff. If you launch ./manage.py shell, can you check where rest_framework is coming from? That might be revealing.

>>> import rest_framework
>>> print(rest_framework.__file__)
<location of rest_framework here>
12

I’ve seen that sys.path munging and that is both abstruse and it is not where my dependencies such as rest_framework live (which are of course in a virtualenv somewhere).

Also in a standard shell inside that environment it can find the dependencies, but for some weird reason sphinx seems to run in its own environment? I still have to figure out which python that uses and why that can’t find the packages.

13

Hello everyone!

I’ve been digging with sphinx inside a Django project with some successful results.
I followed this post, a bit outdated (Sphinx v. 1.7.5), with the sphinx-apidoc -o . .. command.

Do you have some kind of sphinx configuration template to document models, views, serializers or even python functions? @mblayman @atcrank @alper

Sorry if you are bothered by the mention. You can disregard this message.

Thanks!

14

We aren’t super strict about about docstring formatting, but a lot of my team’s code uses Google Style docstring formats. That let’s us use this Napoleon extension to extract some more semantic meaning out of docstrings.

https://sphinxcontrib-napoleon.readthedocs.io/en/latest/

We also have completely type annotated all the code, so I’d like to research what Sphinx options are available to handle type annotations. I haven’t done that research yet.

1 Like
15

I’ve tried sphinx with the autodoc and viewcode extensions and I have to say it’s pretty nice.

Now I have to try napoleon. For type annotations, there’s a library mentioned in this issue that might be useful.

Thanks Matt!

2 Likes