django-actual-admin-docs


Namedjango-actual-admin-docs JSON
Version 0.5 PyPI version JSON
download
home_pagehttps://github.com/bartTC/django-actual-admin-docs
SummaryRender Markdown documentation in the Django Admin.
upload_time2024-11-06 11:46:17
maintainerNone
docs_urlNone
authorMartin Mahner
requires_python<4.0,>=3.9
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # 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.

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/bartTC/django-actual-admin-docs",
    "name": "django-actual-admin-docs",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.9",
    "maintainer_email": null,
    "keywords": null,
    "author": "Martin Mahner",
    "author_email": "martin@mahner.org",
    "download_url": "https://files.pythonhosted.org/packages/6b/df/e48857fda8045fa7e719c0a5eb3de58e30acad8710ded450da62186d1dd1/django_actual_admin_docs-0.5.tar.gz",
    "platform": null,
    "description": "# django-actual-admin-docs\n\nRender Markdown documentation directly in the Django admin`.\n\n- Support for nested subfolders\n- Comprehensive Markdown format (link to which spec)\n- Provides default styles for Markdown rendering\n\n## Installation\n\n1. Install the `django-actual-admin-docs` package. If you have `pygments` installed, code blocks are automatically highlighted.\n\n2. Add `actual_admin_docs` to your `INSTALLED_APPS` setting:\n\n   ```python \n   INSTALLED_APPS = [\n     \"django.contrib.admin\",\n     \"actual_admin_docs\",\n     ...\n   ]\n   ```\n   \n3. Add the documentation urlpattern, above your admin urls:\n\n   ```python\n   from django.contrib import admin\n   from django.urls import include, path\n   \n   urlpatterns = [\n       path(\"admin/docs/\", include(\"actual_admin_docs.urls\")),\n       path(\"admin/\", admin.site.urls),\n   ]\n   ```\n4. Add a `DOCS_ROOT` setting which should be a `pathlib.Path` pointing to the docs directory:\n\n   ```python \n   DOCS_ROOT = BASE_DIR / \"docs\"\n   ```\n\n## Documentation folder structure\n\nYou can use folders, subfolders, files in folders, etc.\n\n```\n\ud83d\uddc2 docs/\n\u2502\n\u251c\u2500\u2500 \ud83d\uddc2 subfolder   \n\u2502   \u2502   \n\u2502   \u251c\u2500\u2500 \ud83d\uddc2 subfolder with spaces\n\u2502   \u2502   \u2514\u2500\u2500 \ud83d\udcdd another-file.md\n\u2502   \u2502 \n\u2502   \u251c\u2500\u2500 \ud83d\udcdd another-file.md\n\u2502   \u2514\u2500\u2500 \ud83d\udcdd index.md\n\u2502\n\u251c\u2500\u2500 \ud83d\uddc2 img    \n\u2502   \u2514\u2500\u2500 \ud83c\udf01 cat_studying_glasses.jpg\n\u2502\n\u251c\u2500\u2500 \ud83d\udcdd index.md\n\u2514\u2500\u2500 \ud83d\udcdd markdown-sample.md\n```\n\nUse regular Markdown links to link to other documents or objects:\n\n```markdown\nA link to [another document](./markdown-sample.md) is just a regular Markdown link. Documents in subdirectories [are supported too](./subfolder/another-file.md).\n\nFor images, downloads etc. use regular markdown markup too:\n\n![A cat judging your code](./img/cat_studying_glasses.jpg)\n[Click to download](./img/./img/cat_studying_glasses.jpg)\n```\n\n## Custom CSS\n\nOverwrite the `actual-admin-docs.css` file to add your custom styles.\n\n\n-----\n\n# \ud83e\udd3a Local Development\n\n```bash\n$ poetry install\n$ poetry run pytest\n$ DJANGO_SETTINGS_MODULE=actual_admin_docs.tests.testproject.settings poetry run django-admin runserver\n```\n# Changelog\n\n## v0.5 2024-11-06\n\n- Removed 'highlight' extras marker. If `pygments` is installed, code blocks are highlighted, and if not, then not. \n\n## v0.4 2024-11-06\n\n- Sample documentation for testing purpose is now part of the module.\n- Added testing with docs.\n\n## v0.3 2024-11-06\n\n- Improved local test setup,\n- Index files are consistently recognized in subfolders.\n- Pygments as a dependency is now optional.\n\n## v0.2 2024-11-05\n\n- Added syntax highlighting for fenced code blocks.\n- Added Pygments as a dependency.\n\n## v0.1 2024-11-05\n\n- Initial version.",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Render Markdown documentation in the Django Admin.",
    "version": "0.5",
    "project_urls": {
        "Homepage": "https://github.com/bartTC/django-actual-admin-docs"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "9a87072552e462186710f344a447c6e5b54cb92255acdf4a7acc9efadbc04ab3",
                "md5": "9875a13cad0fe922fd4a68da35fed1af",
                "sha256": "8e4b0f1bb5de0fffedcae923eb6bc13ed9bb741a583e3f8899e806aea63541e6"
            },
            "downloads": -1,
            "filename": "django_actual_admin_docs-0.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9875a13cad0fe922fd4a68da35fed1af",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.9",
            "size": 82563,
            "upload_time": "2024-11-06T11:46:15",
            "upload_time_iso_8601": "2024-11-06T11:46:15.816500Z",
            "url": "https://files.pythonhosted.org/packages/9a/87/072552e462186710f344a447c6e5b54cb92255acdf4a7acc9efadbc04ab3/django_actual_admin_docs-0.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "6bdfe48857fda8045fa7e719c0a5eb3de58e30acad8710ded450da62186d1dd1",
                "md5": "18daaf7f519a66d0173bb6834914aac2",
                "sha256": "4c81229fb6f427861f5589e31d48d0026d5a465495ce5c667f6d1499c1daf8d4"
            },
            "downloads": -1,
            "filename": "django_actual_admin_docs-0.5.tar.gz",
            "has_sig": false,
            "md5_digest": "18daaf7f519a66d0173bb6834914aac2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.9",
            "size": 81802,
            "upload_time": "2024-11-06T11:46:17",
            "upload_time_iso_8601": "2024-11-06T11:46:17.067205Z",
            "url": "https://files.pythonhosted.org/packages/6b/df/e48857fda8045fa7e719c0a5eb3de58e30acad8710ded450da62186d1dd1/django_actual_admin_docs-0.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-11-06 11:46:17",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "bartTC",
    "github_project": "django-actual-admin-docs",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "django-actual-admin-docs"
}
Martin Mahner
Elapsed time: 0.37609s