django-classy-doc 0.1.0

Django package to generate ccbv.co.uk-style documentation for your own code

Django Classy DOC

django-classy-doc brings Classy Class-Based Views-style docs to your own code

Installation

From PyPI

pip install django-classy-doc

From the repo

pip install -e https://gitlab.levitnet.be/levit/django-classy-doc.git

Getting started

First add 'django_classy_doc', to your INSTALLED_APPS in your settings.py file.

To generate the documentation statically, run

./manage.py classify

This will create documentation for your project and save the output in ./output

For more usage information run

./manage.py classify --help

If instead (or alongside) of generating the documentation statically, you can also have Django render the documentation by adding the following line to your urlpatterns in urls.py

urlpatterns = [
  ...
  path('__doc__/', include('django_classy_doc.urls')),
]

Configuration

Set these in your settings.py file.

django-classy-doc has several configuration options, the most important are CLASSY_DOC_BASES, CLASSY_DOC_MODULE_TYPES and CLASSY_DOC_KNOWN_APPS.

CLASSY_DOC_BASES

This is the list of strings of the base modules you want to document, if you leave it unset, django-classy-doc will document every application from your INSTALLED_APPS

django-classy-docs will string-match everything from your INSTALLED_APPS that starts with any of the mentioned strings

ex:

CLASSY_DOC_BASES = ['catalog', 'custom_auth', 'account']

CLASSY_DOC_MODULE_TYPES

These are the modules type django-classy-doc will try to import from every application that matches CLASSY_DOC_BASES. It defaults to ['models', 'views'].

So, assuming your project looks like this:

+  mod1
|  +  apps.py
|  +  admin.py
|  +  models.py
|  +  views.py
+  mod2
|  +  apps.py
|  +  admin.py
|  +  models.py
+  mod3
|  +  apps.py
|  +  views.py

The following modules will be documented: mod1.models, mod1.views, mod2.models, mod3.views

CLASSY_DOC_KNOWN_APPS

A dictionary of lists that represents the "known apps" that you want to hide by default. This means that properties and methods present in your classes (that extend these bases classes) that are only defined in these base classes, will be hidden at first. All sections of the generated documentation will have a checkbox for each of these known apps that will let you show/hide thes properties and methods.

If left unset, it will default to {'django': ['django']}

ex:

CLASSY_KNOWN_APPS = {
  'django': ['django'],                                                      
  'DRF': ['rest_framework', 'django_filters'],
  'wagtail': ['wagtail', 'treebeard', 'modelcluster'],
}

Other configuration

CLASSY_DOC_ALSO_INCLUDE

A list of modules (that would otherwise not be matched) that django-classy-doc should also try to document. This defaults to an empty list.

CLASSY_DOC_ALSO_EXCLUDE

A list of modules (that would otherwise be matched) that django-classy-doc should not try to document. This defaults to an empty list.

CLASSY_DOC_NON_INSTALLED_APPS

A list of modules, not present in INSTALLED_APPS to include in the search for modules. This is mostly useful if you want to document DJango itself.

Recipes

CCBV

In order to replicate CCBV, these are the settings you should set:

CLASSY_DOC_BASES = ['django.views.generic']
CLASSY_DOC_NON_INSTALLED_APPS = ['django.views.generic']
CLASSY_DOC_MODULE_TYPES = [
    'base',
    'dates',
    'detail',
    'edit',
    'list',
]
CLASSY_DOC_KNOWN_APPS = {}

If you'd like to include django.contrib.views in your documentation, you'll first have to include them in your urls.py:

urlpatterns = [
  ...
  path('accounts/', include('django.contrib.auth.urls')),
  ...
]

Once this is done, you can then use the following settings:

CLASSY_DOC_BASES = ['django.views.generic', 'django.contrib.auth']
CLASSY_DOC_NON_INSTALLED_APPS = ['django.views.generic']
CLASSY_DOC_MODULE_TYPES = [
    'base',
    'dates',
    'detail',
    'edit',
    'list',
    'views',
]
CLASSY_DOC_KNOWN_APPS = {}

CDRF

In order to replicate CDRF, these are the settings you should set:

CLASSY_DOC_BASES = ['rest_framework']
CLASSY_DOC_MODULE_TYPES = ['generics', 'mixins', 'pagination', 'serializers', 'views', 'viewsets']
CLASSY_DOC_KNOWN_APPS = {}

CDDB

In order to replicate CDDB, these are the settings you should set:

CLASSY_DOC_BASES = ['django.db', 'django.db.models']
CLASSY_DOC_NON_INSTALLED_APPS = ['django.db.models', 'django.db']
CLASSY_DOC_MODULE_TYPES = [
    'base',
    'fields',
    'enums',
    'expressions',
    'constraints',
    'indexes',
    'lookups',
    'aggregates',
    'constants',
    'deletion',
    'functions',
    'manager',
    'query_utils',
    'sql',
    'options',
    'query',
    'signals',
    'utils',
    'transaction',
]
CLASSY_DOC_KNOWN_APPS = {}

CDF

In order to replicate CDF, these are the settings you should set:

CLASSY_DOC_BASES = ['django.forms']
CLASSY_DOC_NON_INSTALLED_APPS = ['django.forms']
CLASSY_DOC_MODULE_TYPES = [
    'boundfield',
    'fields',
    'forms',
    'formsets',
    'models',
    'renderers',
    'widgets',
]
CLASSY_DOC_KNOWN_APPS = {}

MkDocs Integration

mkdocstrings Handler

django-classy-doc provides a custom handler for mkdocstrings that allows you to embed class documentation directly in your MkDocs-based documentation.

Installation

Install with the mkdocs extra:

pip install django-classy-doc[mkdocs]

Configuration

In your mkdocs.yml, configure the handler:

plugins:
  - mkdocstrings:
      handlers:
        classydoc:
          # Handler options (all optional)
          options:
            show_source: true
            show_mro: true
            show_attributes: true
            show_methods: true
            show_fields: true
            heading_level: 2

Make sure to set your DJANGO_SETTINGS_MODULE environment variable so the handler can access your Django configuration:

export DJANGO_SETTINGS_MODULE=myproject.settings

Usage

In your markdown files, use the ::: classydoc directive to include class documentation:

# My Model Documentation

::: myapp.models.MyModel
    handler: classydoc
    options:
      show_source: true
      show_mro: true

The handler supports these options:

Option	Default	Description
show_source	true	Display source code for methods
show_mro	true	Display Method Resolution Order
show_attributes	true	Display class attributes
show_methods	true	Display methods with signatures
show_fields	true	Display Django model fields
heading_level	2	Starting heading level for sections

Markdown Formatter

For programmatic use, django-classy-doc provides a MarkdownFormatter class that generates mkdocs-compatible markdown from classified class data.

Usage

from django_classy_doc.utils import build
from django_classy_doc.formatters.markdown import MarkdownFormatter

# Get class data
klass_data = build('myapp.models.MyModel')

# Format as markdown
formatter = MarkdownFormatter(klass_data)
markdown_content = formatter.format()

The formatter supports Google-style docstrings and will parse sections like Args, Returns, Examples, and Notes into properly formatted markdown.