djadmin-classy-doc

A Django admin documentation generator plugin for django-admin-deux that creates django-classy-doc style documentation for factory-generated views.

Overview

This plugin introspects djadmin's ViewFactory to automatically generate comprehensive documentation about how views are constructed, including:

• View Discovery: Automatically finds all registered views across your Django models
• View Classification: Uses django-classy-doc to extract methods, attributes, and base classes
• Plugin Attribution: Tracks which plugins contribute mixins and attributes to each view
• Static Generation: Generates JSON documentation that can be processed into HTML or other formats
• Live Documentation: (Phase 6+) Serve documentation through Django views

Installation

Install from PyPI:

pip install djadmin-classy-doc

Or add to your django-admin-deux installation:

pip install django-admin-deux[full]

Quick Start

1. Add to INSTALLED_APPS

INSTALLED_APPS = [
    # ...
    'django_classy_doc',  # Required dependency
    'djadmin_classy_doc',  # This plugin
    # ...
]

2. Generate Documentation

python manage.py generate_djadmin_docs --output-dir ./docs/djadmin --format json

This generates a views.json file with metadata about all your registered views:

{
  "views": [
    {
      "name": "ProductListView",
      "model": "webshop.product",
      "action_type": "general",
      "view_class": "ProductListView",
      "module": "djadmin.factories.base",
      "methods": [...],
      "attributes": [...],
      "construction_info": {
        "base_class": { "class": "ListView", "plugin": "...", "hook": "..." },
        "mixins": [...],
        "attributes": {...},
        "bound_methods": {
          "get_queryset": { "action_class": "ListAction", "plugin": "...", "hook": "..." },
          "get_context_data": { "action_class": "ListAction", "plugin": "...", "hook": "..." }
        }
      }
    },
    ...
  ],
  "summary": {
    "total_views": 49,
    "model_views": 49,
    "site_views": 3,
    "models": 8
  }
}

3. View the Data

The generated JSON includes:

• name: The generated view class name
• model: Django model being viewed (in app.Model format), or null for site-level views
• action_type: Type of action ('general', 'bulk', or 'record')
• view_class: Name of the view class
• module: Module where the view class is defined
• methods: List of all methods on the view (introspected from real class)
• attributes: List of all attributes on the view (introspected from real class)
• construction_info (Phase 2+): Detailed information about how the view was constructed:
  • base_class: Which class is the base (with plugin attribution)
  • mixins: All mixins applied (with plugin attribution)
  • attributes: View attributes (with plugin attribution)
  • bound_methods: Methods bound from actions (with action class and plugin attribution)

Features

Phase 1 (Complete - MVP)

• ✅ ViewFactory introspection
• ✅ django-classy-doc integration
• ✅ View discovery and classification
• ✅ JSON output generation
• ✅ Management command

Phase 2 (Complete - Site-Level Actions + Plugin Attribution)

• ✅ Plugin attribution tracking (mixins, attributes, bound methods)
• ✅ Site-level actions support (dashboard views with model=None)
• ✅ Construction info with full plugin attribution

Phase 3 (Complete - Real Class Introspection & Action Method Attribution)

• ✅ Real class introspection using django-classy-doc
• ✅ Bound method tracking with action class attribution
• ✅ MRO annotation with plugin sources
• ✅ Full method signatures and docstrings from real classes

Phase 4+

• 🔜 HTML template generation
• 🔜 Generic action type documentation
• 🔜 Live documentation views
• 🔜 Search and navigation

How It Works

1. View Discovery

The plugin iterates through all registered models in your AdminSite and collects:

• General actions (ListAction, AddAction)
• Bulk actions (DeleteBulkAction)
• Record actions (EditAction, DeleteAction, ViewAction)

For each action, it uses ViewFactory to create the corresponding view class.

2. View Classification

Uses django-classy-doc's introspection to extract:

• All methods on the view class and their signatures
• All class attributes
• Complete method resolution order (MRO)
• Docstrings and source code (when available)

3. View Context

Adds djadmin-specific metadata:

• The original action instance
• The model being administered
• The model admin instance

Usage Examples

Generate Documentation

# JSON format (Phase 1)
python manage.py generate_djadmin_docs --format json

# HTML format (Phase 4+)
python manage.py generate_djadmin_docs --format html

# Custom output directory
python manage.py generate_djadmin_docs --output-dir /var/www/docs/djadmin

Programmatic Access

from djadmin_classy_doc.view_introspector import ViewIntrospector
from djadmin_classy_doc.classifier import ClassifierAdapter

# Get all registered views
introspector = ViewIntrospector()
views = introspector.get_registered_views()

# Classify a view
classifier = ClassifierAdapter(introspector)
for view_info in views:
    klass_data = classifier.classify_djadmin_view(
        view_info['view_class'],
        view_info['action']
    )
    print(f"Methods: {list(klass_data['methods'].keys())}")
    print(f"Attributes: {list(klass_data['attributes'].keys())}")

Architecture

Core Components

ViewIntrospector (view_introspector.py)

• Discovers all registered views in AdminSite
• Determines action types
• Returns structured view information

ClassifierAdapter (classifier.py)

• Wraps django-classy-doc's classify() function
• Adds djadmin-specific metadata
• Returns fully classified view information

Management Command (management/commands/generate_djadmin_docs.py)

• Coordinates view discovery and classification
• Generates JSON/HTML output
• Provides command-line interface

Data Flow

AdminSite._registry
        ↓
ViewIntrospector.get_registered_views()
        ↓
    [View Info Objects]
        ↓
ClassifierAdapter.classify_djadmin_view()
        ↓
    [Classified View Data]
        ↓
Management Command (serialization)
        ↓
    views.json / views.html

Testing

Running Tests

From the main django-admin-deux directory (where just is available):

# Run all tests
just test

# Run plugin tests only
just test-file djadmin-classy-doc/tests/test_source_generator.py

# Run specific test class
just test-match "TestSourceGeneratorSignature"

# Run with verbose output
just test-verbose

Test Organization

The plugin's tests live in djadmin-classy-doc/tests/ and are automatically discovered by the main project's pytest configuration:

• test_view_introspector.py - Tests for view discovery and introspection
• test_classifier.py - Tests for view classification and metadata extraction
• test_source_generator.py - Tests for synthetic source code generation (Phase 3)

Coverage

All tests must maintain >80% code coverage:

# Run tests with coverage report
just test-coverage

# View HTML coverage report
just coverage-report

Requirements

• Django ≥5.2
• django-admin-deux ≥0.1.0
• django-classy-doc
• djp ≥0.1.0

License

Same as django-admin-deux

Credits

• Built on django-classy-doc patterns
• Integrates with django-admin-deux factory system
• Uses djp plugin system