Skip to main content

A simple documentation app for Django.

Project description

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

pip install django-easy-docs-bs5

You will need to add easy_docs to your INSTALLED_APPS in your settings.py file:

INSTALLED_APPS = [
    ...
    'easy_docs',
    ...
]

You will also need to add the following to your urls.py file:

from django.urls import path, include

urlpatterns = [
    ...
    path('easy_docs/', include('easy_docs.urls')),
    ...
]

This package also takes advantage of several other packages, including:

These are installed automatically when you install django-easy-docs-bs5, but you will need to add them to your INSTALLED_APPS as well:

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.

Usage

To use Easy Docs, you will need to add the following to your base template:

{% 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:

{% 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.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-easy-docs-bs5-1.0.1.tar.gz (12.8 kB view details)

Uploaded Source

Built Distribution

django_easy_docs_bs5-1.0.1-py3-none-any.whl (20.4 kB view details)

Uploaded Python 3

File details

Details for the file django-easy-docs-bs5-1.0.1.tar.gz.

File metadata

  • Download URL: django-easy-docs-bs5-1.0.1.tar.gz
  • Upload date:
  • Size: 12.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.2

File hashes

Hashes for django-easy-docs-bs5-1.0.1.tar.gz
Algorithm Hash digest
SHA256 0de1256d3c5775928be30e25b4a202d99b4fd5a61c4d77969e771ef2a190ebe8
MD5 2ac15394a1e5e0b90f297cd76424c178
BLAKE2b-256 70e7b64ad759add53d58ce27f18cab862afa3a5a37b24755fa6f4bca9bc8f2a4

See more details on using hashes here.

Provenance

File details

Details for the file django_easy_docs_bs5-1.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for django_easy_docs_bs5-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 380c1c5096651675d7973340ba7a7ae5e1fc4b0ab65685e010f57223ad8e05a8
MD5 2e06127bde9620bd47130db56e592cab
BLAKE2b-256 0c9bf69736a9db8732ad9e84b8a62451865c3b13fcf6ac4e18bae181e7a7fa83

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page