# Documenting models and fields **URL:** \ **Category:** Using Django\ **Created:** [November 10, 2020, 10:25am UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162 "2020-11-10T10:25:56Z")\ **Posts on this page:** 15\ **Page:** 1
**Author:** ![alper](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/alper/32/1370_2.png) [@alper](https://forum.djangoproject.com/u/alper)\ **Post date:** [November 10, 2020, 10:25am UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/1 "2020-11-10T10:25:56Z")
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? ---
**Author:** ![atcrank](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/atcrank/32/2029_2.png) [@atcrank](https://forum.djangoproject.com/u/atcrank)\ **Post date:** [November 11, 2020, 12:34am UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/2 "2020-11-11T00:34:01Z")
We use this contrib app. > **[The Django admin documentation generator — Django 3.1.2 documentation](https://django.readthedocs.io/en/stable/ref/contrib/admin/admindocs.html)** 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](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. ---
**Author:** ![alper](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/alper/32/1370_2.png) [@alper](https://forum.djangoproject.com/u/alper)\ **Post date:** [November 11, 2020, 10:11am UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/3 "2020-11-11T10:11:51Z")
What does that mean do we need to adjust this? ---
**Author:** ![atcrank](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/atcrank/32/2029_2.png) [@atcrank](https://forum.djangoproject.com/u/atcrank)\ **Post date:** [November 11, 2020, 10:37am UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/4 "2020-11-11T10:37:30Z")
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. ---
**Author:** ![alper](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/alper/32/1370_2.png) [@alper](https://forum.djangoproject.com/u/alper)\ **Post date:** [November 11, 2020, 10:52am UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/5 "2020-11-11T10:52:58Z")
> [@atcrank](#): > > 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. I’ll have to try this. Team said they couldn’t get it to work so now they have a weird script in place. ---
**Author:** ![alper](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/alper/32/1370_2.png) [@alper](https://forum.djangoproject.com/u/alper)\ **Post date:** [November 11, 2020, 12:49pm UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/6 "2020-11-11T12:49:48Z")
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 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 "", line 1006, in _gcd_import File "", line 983, in _find_and_load File "", 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? ---
**Author:** ![alper](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/alper/32/1370_2.png) [@alper](https://forum.djangoproject.com/u/alper)\ **Post date:** [November 11, 2020, 12:50pm UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/7 "2020-11-11T12:50:25Z")
I think what I want to have may likely be something like: [https://pdoc3.github.io/pdoc/](https://pdoc3.github.io/pdoc/) ---
**Author:** ![alper](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/alper/32/1370_2.png) [@alper](https://forum.djangoproject.com/u/alper)\ **Post date:** [November 11, 2020, 1:10pm UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/8 "2020-11-11T13:10:47Z")
Pdoc3 also doesn’t work because it gets tangled up with django. ---
**Author:** ![mblayman](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/mblayman/32/101_2.png) [@mblayman](https://forum.djangoproject.com/u/mblayman)\ **Post date:** [November 12, 2020, 3:56pm UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/9 "2020-11-12T15:56:45Z")
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. ---
**Author:** ![alper](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/alper/32/1370_2.png) [@alper](https://forum.djangoproject.com/u/alper)\ **Post date:** [November 13, 2020, 9:20am UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/10 "2020-11-13T09:20:17Z")
Yeah, the `setup()` is literally in there. It’s just not finding all the imports of the django project itself for some strange reason. ---
**Author:** ![mblayman](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/mblayman/32/101_2.png) [@mblayman](https://forum.djangoproject.com/u/mblayman)\ **Post date:** [November 13, 2020, 3:16pm UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/11 "2020-11-13T15:16:36Z")
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. ```python 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. ```python >>> import rest_framework >>> print(rest_framework. __file__ ) ``` ---
**Author:** ![alper](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/alper/32/1370_2.png) [@alper](https://forum.djangoproject.com/u/alper)\ **Post date:** [November 13, 2020, 10:08pm UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/12 "2020-11-13T22:08:14Z")
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. ---
**Author:** ![marcorichetta](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/marcorichetta/32/26473_2.png) [@marcorichetta](https://forum.djangoproject.com/u/marcorichetta)\ **Post date:** [April 5, 2021, 9:34pm UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/13 "2021-04-05T21:34:10Z")
Hello everyone! I’ve been digging with sphinx inside a Django project with some _successful_ results. I followed [this post](https://www.freecodecamp.org/news/sphinx-for-django-documentation-2454e924b3bc/), 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! ---
**Author:** ![mblayman](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/mblayman/32/101_2.png) [@mblayman](https://forum.djangoproject.com/u/mblayman)\ **Post date:** [April 5, 2021, 11:05pm UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/14 "2021-04-05T23:05:13Z")
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/](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. ---
**Author:** ![marcorichetta](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/marcorichetta/32/26473_2.png) [@marcorichetta](https://forum.djangoproject.com/u/marcorichetta)\ **Post date:** [April 6, 2021, 3:56pm UTC](https://forum.djangoproject.com/t/documenting-models-and-fields/5162/15 "2021-04-06T15:56:36Z")
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. > > > I may be a victim of circumstances here, but I was left a bit confused. > I found http://sphinxcontrib-napoleon.readthedocs.io/ before realizing per the... Thanks Matt!