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!

1 Like