djadmin-classy-doc 0.1.0
Django admin documentation generator using django-classy-doc patterns
Requires Python: >=3.11

# 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:

```bash
pip install djadmin-classy-doc
```

Or add to your django-admin-deux installation:

```bash
pip install django-admin-deux[full]
```

## Quick Start

### 1. Add to INSTALLED_APPS

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

### 2. Generate Documentation

```bash
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:

```json
{
  "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

```bash
# 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

```python
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):

```bash
# 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:

```bash
# 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](https://ccbv.co.uk/) patterns
- Integrates with [django-admin-deux](https://github.com/emmaDelescolle/django-admin-deux) factory system
- Uses [djp](https://github.com/simonw/djp) plugin system