Metadata-Version: 2.1
Name: django-actual-admin-docs
Version: 0.5
Summary: Render Markdown documentation in the Django Admin.
Home-page: https://github.com/bartTC/django-actual-admin-docs
License: MIT
Author: Martin Mahner
Author-email: martin@mahner.org
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: django
Requires-Dist: markdown-it-py[linkify,plugins] (>=3.0.0,<4.0.0)
Description-Content-Type: text/markdown

# django-actual-admin-docs

Render Markdown documentation directly in the Django admin`.

- Support for nested subfolders
- Comprehensive Markdown format (link to which spec)
- Provides default styles for Markdown rendering

## Installation

1. Install the `django-actual-admin-docs` package. If you have `pygments` installed, code blocks are automatically highlighted.

2. Add `actual_admin_docs` to your `INSTALLED_APPS` setting:

   ```python 
   INSTALLED_APPS = [
     "django.contrib.admin",
     "actual_admin_docs",
     ...
   ]
   ```
   
3. Add the documentation urlpattern, above your admin urls:

   ```python
   from django.contrib import admin
   from django.urls import include, path
   
   urlpatterns = [
       path("admin/docs/", include("actual_admin_docs.urls")),
       path("admin/", admin.site.urls),
   ]
   ```
4. Add a `DOCS_ROOT` setting which should be a `pathlib.Path` pointing to the docs directory:

   ```python 
   DOCS_ROOT = BASE_DIR / "docs"
   ```

## Documentation folder structure

You can use folders, subfolders, files in folders, etc.

```
🗂 docs/
│
├── 🗂 subfolder   
│   │   
│   ├── 🗂 subfolder with spaces
│   │   └── 📝 another-file.md
│   │ 
│   ├── 📝 another-file.md
│   └── 📝 index.md
│
├── 🗂 img    
│   └── 🌁 cat_studying_glasses.jpg
│
├── 📝 index.md
└── 📝 markdown-sample.md
```

Use regular Markdown links to link to other documents or objects:

```markdown
A link to [another document](./markdown-sample.md) is just a regular Markdown link. Documents in subdirectories [are supported too](./subfolder/another-file.md).

For images, downloads etc. use regular markdown markup too:

![A cat judging your code](./img/cat_studying_glasses.jpg)
[Click to download](./img/./img/cat_studying_glasses.jpg)
```

## Custom CSS

Overwrite the `actual-admin-docs.css` file to add your custom styles.


-----

# 🤺 Local Development

```bash
$ poetry install
$ poetry run pytest
$ DJANGO_SETTINGS_MODULE=actual_admin_docs.tests.testproject.settings poetry run django-admin runserver
```
# Changelog

## v0.5 2024-11-06

- Removed 'highlight' extras marker. If `pygments` is installed, code blocks are highlighted, and if not, then not. 

## v0.4 2024-11-06

- Sample documentation for testing purpose is now part of the module.
- Added testing with docs.

## v0.3 2024-11-06

- Improved local test setup,
- Index files are consistently recognized in subfolders.
- Pygments as a dependency is now optional.

## v0.2 2024-11-05

- Added syntax highlighting for fenced code blocks.
- Added Pygments as a dependency.

## v0.1 2024-11-05

- Initial version.
