Ocyan Admin Theme

ocyan.plugin.admin-theme is an opt-in, reusable presentation layer for Django administration. It themes Django admin templates and static assets; it does not replace Django authentication, permissions, routes, model registration, or Wagtail administration.

Repository structure

This is a first-class Ocyan plugin repository. It follows the current, modernised plugin form: source in src/, PEP 621 metadata in pyproject.toml, namespaced package data, focused Django tests, a changelog, and a source-controlled non-deploying Jenkinsfile. Older Ocyan plugins commonly use a flat setup.py layout; this package deliberately does not copy that legacy structure.

Install and activate

Install the package as an explicit project dependency. Add the app before django.contrib.admin so Django’s app-template discovery selects the theme:

INSTALLED_APPS = [
    "ocyan.plugin.admin_theme",
    "django.contrib.admin",
    # remaining applications
]

Leaving the app out intentionally preserves standard Django administration. ocyan.main does not require this package.

Namespace compatibility status

This distribution uses Python's native (PEP 420) ocyan.plugin namespace. It is intentionally independent of ocyan.main. A host can use it only when the installed ocyan and ocyan.plugin parent packages are also PEP-420-compatible. The current legacy MandelBlogStack parent distributions still use pkg_resources.declare_namespace, which prevents Python from discovering this package in the same environment. That family-wide namespace modernisation is a prerequisite for MandelStudio integration and RC release; this package does not ship compatibility shims that would perpetuate the old namespace mechanism.

Branding

Projects configure their own identity; this package deliberately ships no project logo or private asset.

OCYAN_ADMIN_THEME = {
    "company_name": "MandelBlog",
    "product_name": "Operations Platform",
    "compact_logo": "M",
    "logo_url": "/static/project/brand/logo.svg",
    "logo_dark_url": "/static/project/brand/logo-dark.svg",
    "compact_logo_url": "/static/project/brand/icon.svg",
    "compact_logo_dark_url": "/static/project/brand/icon-dark.svg",
    "favicon_url": "/static/project/brand/favicon.svg",
    "application_icon_url": "/static/project/brand/icon.svg",
    "login_heading": "Welcome back",
    "login_supporting_text": "Manage your authorised operations from one place.",
    "accent_color": "#1769aa",
}

Branding URLs accept root-relative paths or explicit HTTP(S) URLs only. Prefer project-owned SVG assets for crisp high-DPI rendering. The package has safe text/mark fallbacks if no assets are configured.

Compatibility and accessibility

The initial release line supports Python 3.12 and Django 5.2 through 5.x. It has no Wagtail dependency and can coexist with Wagtail because it only overrides Django-admin templates. It uses native form labels, Django’s CSRF form flow, visible focus treatments, reduced-motion handling, and forced colours fallbacks.

Run the test suite with:

DJANGO_SETTINGS_MODULE=tests.settings python -m django test tests

Build artifacts with:

python -m build

Before an RC, test a built wheel and sdist in clean environments and run a project integration test with the theme both enabled and intentionally absent.

Scope and fallback

The package themes Django administration only. It does not replace Django authentication, routing, permissions, model registration, or Wagtail admin. Projects can opt out by removing the app from INSTALLED_APPS; standard Django admin templates then remain in use.