Generate docs for django models

Generate extensible Markdown documentation for Django models. Developed for cross-team collaboration when iterating on on data model specifications.

User quickstart with an existing Django project

Install into your project requirements from github (pip install git+https://github.com/jakekara/django-model-docs.git) or from pypi with pip install django-model-docs.

Add "demo_django_app" to your Django app's INSTALLED_APPS (usually in settings.py).

Generate Markdown documentation YOUR_APP

python manage.py generate-model-docs YOUR_APP

That's it. The rest of this doc is for developing and extending this tool.

Dev quick start

# set up a virtual env however you like. here's what I like:
python -m venv venv 
. ./venv bin activate

# set up dev stuff
pip install -r requirements.txt

# install the package in editable mode
pip install -e .

# generate docs for model(s) in the demo app
cd demo_django_project
python manage.py generate-model-docs demo_django_app

The output looks like this at the moment:

# `demo_django_app`` app`

_This file was auto-generated Django Model Docs Generator.  Do not edit this file directly._

A demo Django App. Note that this text will be pulled from the app's docstring and used in the default output of `generate-model-docs`.

## `person` model

Person(id, first_name, last_name, shoeStyle)

|    Field   |Description|                                                          Data type                                                         |Nullable|Default|
|------------|-----------|----------------------------------------------------------------------------------------------------------------------------|--------|-------|
|    `id`    |           |                                                        BigAutoField                                                        |  False |   -   |
|`first_name`|           |                                                          CharField                                                         |  False |   -   |
| `last_name`|           |                                                          CharField                                                         |  False |   -   |
| `shoeStyle`|           |CharField<br><br>Choices (stored value : human readable)<br><br>- `LO` : `LOAFER`<br>- `BO` : `BOOT`<br>- `DR` : `DRESS`<br>|  False |   -   |

Tests

Tests need to be run in the context of the demo_django_app.

cd demo_django_project
python manage.py test django-model-docs

To run the test suite against every supported Python version, use the command tox (you must have each Python version available to tox). You should see output like:

  py39: OK (2.44=setup[2.08]+cmd[0.36] seconds)
  py310: OK (2.04=setup[1.75]+cmd[0.30] seconds)
  py311: OK (2.19=setup[1.86]+cmd[0.33] seconds)
  py312: OK (6.02=setup[5.63]+cmd[0.39] seconds)
  congratulations :) (12.72 seconds)

If you're using pyenv to manage versions, you need to run pyenv local 3.9 3.10 3.11 3.12 to make these versions accessible to tox from in the project environment.