# django-easy-docs-bs5
A simple, opinionated way to add documentation to your website. Add a "Help" button to any page, and intuitively build the documentation for your Django app. Compatible with Bootstrap 5
This project is still in its early stages of development, and any contributors are welcomed.
It has only been tested on Django 4.0 and up. For earlier Django releases, use with caution.
If you want to see something added, please request it! As I said, this is still in early development, and I am open to all suggestions.
If you find a bug, please report it!
## Installation
```bash
pip install django-easy-docs-bs5
```
You will need to add `easy_docs` to your `INSTALLED_APPS` in your `settings.py` file:
```python
INSTALLED_APPS = [
...
'easy_docs',
...
]
```
You will also need to add the following to your `urls.py` file:
```python
from django.urls import path, include
urlpatterns = [
...
path('easy_docs/', include('easy_docs.urls')),
...
]
```
This package also takes advantage of several other packages, including:
- [django-markdownx](https://neutronx.github.io/django-markdownx/)
- [django-simple-history](https://django-simple-history.readthedocs.io/en/latest/)
- [django-htmx](https://django-htmx.readthedocs.io/en/latest/)
- [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/) (required for modal functionality)
These are installed automatically when you install `django-easy-docs-bs5`, but you will need to add them to your `INSTALLED_APPS` as well:
```python
INSTALLED_APPS = [
...
'markdownx',
'simple_history',
'django_htmx',
...
]
```
Please see each packages documentation for detailed installation/usage instructions. I also go over the basic installation of each in the Easy Docs [documentation](https://lewisfletcher.github.io/django-easy-docs/installation.html).
## Usage
To use Easy Docs, you will need to add the following to your base template:
```html
{% load easy_docs_tags %}
<head>
...
{% load_dependencies %}
...
</head>
```
This will load the necessary dependencies for Easy Docs to work. You will then be able to load the help button on any page by adding the following to your template:
```html
{% load easy_docs_tags %}
<body>
...
{% load_help_button %}
...
</body>
```
This will load the help button on any page that uses this template. If the page does not have any documentation and a staff member is logged in, it will open the documentation editor when clicked. If the page does have documentation, it will open the documentation viewer.
By default, the help button will be placed exactly where you place it in your template. The documentation editor supports Markdown, and will automatically render any Markdown in the documentation. For more information on Markdown, please see the [following guide](https://www.markdownguide.org/basic-syntax/).
To assist those who are not familiar with Markdown, the documentation editor also includes a live preview of the documentation. This preview will update as you type, and will show you exactly how the documentation will look when it is saved.
A backend system is also provided to allow you to manage the documentation for your site. You can access this by going to ``/docs/all-documentation/``, or by clicking the 'Documentation' header at the top of the document. You will need to be a staff member to access this page. It also includes version control with an option to easily revert to a previous documentation's save.
Documents are flaggable as public, which will allow them to be viewed by non-staff members. This is useful for adding documentation for your users.
Raw data
{
"_id": null,
"home_page": "https://github.com/sploro-git/django-easy-docs-bs5",
"name": "django-easy-docs-bs5",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "django, documentation, docs, easy, simple",
"author": "Sploro",
"author_email": "development@sploro.eu",
"download_url": "https://files.pythonhosted.org/packages/70/e7/b64ad759add53d58ce27f18cab862afa3a5a37b24755fa6f4bca9bc8f2a4/django-easy-docs-bs5-1.0.1.tar.gz",
"platform": null,
"description": "# django-easy-docs-bs5\r\n\r\nA simple, opinionated way to add documentation to your website. Add a \"Help\" button to any page, and intuitively build the documentation for your Django app. Compatible with Bootstrap 5 \r\n\r\nThis project is still in its early stages of development, and any contributors are welcomed.\r\n\r\nIt has only been tested on Django 4.0 and up. For earlier Django releases, use with caution.\r\n\r\nIf you want to see something added, please request it! As I said, this is still in early development, and I am open to all suggestions. \r\n\r\nIf you find a bug, please report it!\r\n\r\n## Installation\r\n\r\n```bash\r\npip install django-easy-docs-bs5\r\n```\r\n\r\nYou will need to add `easy_docs` to your `INSTALLED_APPS` in your `settings.py` file:\r\n\r\n```python\r\nINSTALLED_APPS = [\r\n ...\r\n 'easy_docs',\r\n ...\r\n]\r\n```\r\n\r\nYou will also need to add the following to your `urls.py` file:\r\n\r\n```python\r\nfrom django.urls import path, include\r\n\r\nurlpatterns = [\r\n ...\r\n path('easy_docs/', include('easy_docs.urls')),\r\n ...\r\n]\r\n```\r\n\r\nThis package also takes advantage of several other packages, including:\r\n\r\n- [django-markdownx](https://neutronx.github.io/django-markdownx/)\r\n- [django-simple-history](https://django-simple-history.readthedocs.io/en/latest/)\r\n- [django-htmx](https://django-htmx.readthedocs.io/en/latest/)\r\n- [Bootstrap 5](https://getbootstrap.com/docs/5.0/getting-started/introduction/) (required for modal functionality)\r\n\r\nThese are installed automatically when you install `django-easy-docs-bs5`, but you will need to add them to your `INSTALLED_APPS` as well:\r\n\r\n```python\r\nINSTALLED_APPS = [\r\n ...\r\n 'markdownx',\r\n 'simple_history',\r\n 'django_htmx',\r\n ...\r\n]\r\n```\r\n\r\nPlease see each packages documentation for detailed installation/usage instructions. I also go over the basic installation of each in the Easy Docs [documentation](https://lewisfletcher.github.io/django-easy-docs/installation.html).\r\n\r\n## Usage\r\n\r\nTo use Easy Docs, you will need to add the following to your base template:\r\n\r\n```html\r\n{% load easy_docs_tags %}\r\n\r\n<head>\r\n ...\r\n {% load_dependencies %}\r\n ...\r\n</head>\r\n\r\n```\r\n\r\nThis will load the necessary dependencies for Easy Docs to work. You will then be able to load the help button on any page by adding the following to your template:\r\n\r\n```html\r\n{% load easy_docs_tags %}\r\n\r\n<body>\r\n ...\r\n {% load_help_button %}\r\n ...\r\n</body>\r\n```\r\n\r\nThis will load the help button on any page that uses this template. If the page does not have any documentation and a staff member is logged in, it will open the documentation editor when clicked. If the page does have documentation, it will open the documentation viewer.\r\n\r\nBy default, the help button will be placed exactly where you place it in your template. The documentation editor supports Markdown, and will automatically render any Markdown in the documentation. For more information on Markdown, please see the [following guide](https://www.markdownguide.org/basic-syntax/).\r\n\r\nTo assist those who are not familiar with Markdown, the documentation editor also includes a live preview of the documentation. This preview will update as you type, and will show you exactly how the documentation will look when it is saved.\r\n\r\nA backend system is also provided to allow you to manage the documentation for your site. You can access this by going to ``/docs/all-documentation/``, or by clicking the 'Documentation' header at the top of the document. You will need to be a staff member to access this page. It also includes version control with an option to easily revert to a previous documentation's save.\r\n\r\nDocuments are flaggable as public, which will allow them to be viewed by non-staff members. This is useful for adding documentation for your users.\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple documentation app for Django.",
"version": "1.0.1",
"project_urls": {
"Download": "https://pypi.org/project/django-easy-docs-bs5/",
"Homepage": "https://github.com/sploro-git/django-easy-docs-bs5"
},
"split_keywords": [
"django",
" documentation",
" docs",
" easy",
" simple"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c9bf69736a9db8732ad9e84b8a62451865c3b13fcf6ac4e18bae181e7a7fa83",
"md5": "2e06127bde9620bd47130db56e592cab",
"sha256": "380c1c5096651675d7973340ba7a7ae5e1fc4b0ab65685e010f57223ad8e05a8"
},
"downloads": -1,
"filename": "django_easy_docs_bs5-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e06127bde9620bd47130db56e592cab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20351,
"upload_time": "2024-03-22T08:31:50",
"upload_time_iso_8601": "2024-03-22T08:31:50.723815Z",
"url": "https://files.pythonhosted.org/packages/0c/9b/f69736a9db8732ad9e84b8a62451865c3b13fcf6ac4e18bae181e7a7fa83/django_easy_docs_bs5-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "70e7b64ad759add53d58ce27f18cab862afa3a5a37b24755fa6f4bca9bc8f2a4",
"md5": "2ac15394a1e5e0b90f297cd76424c178",
"sha256": "0de1256d3c5775928be30e25b4a202d99b4fd5a61c4d77969e771ef2a190ebe8"
},
"downloads": -1,
"filename": "django-easy-docs-bs5-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "2ac15394a1e5e0b90f297cd76424c178",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12846,
"upload_time": "2024-03-22T08:31:51",
"upload_time_iso_8601": "2024-03-22T08:31:51.877546Z",
"url": "https://files.pythonhosted.org/packages/70/e7/b64ad759add53d58ce27f18cab862afa3a5a37b24755fa6f4bca9bc8f2a4/django-easy-docs-bs5-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-22 08:31:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sploro-git",
"github_project": "django-easy-docs-bs5",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-easy-docs-bs5"
}
JSON
