Administrator Documentation

Note

This document is the short reference on how to make django-calingen work in a Django project. For a more detailled guide, see Setup Guide (Step by Step).

Installation and Setup

Requirements

Platform, Python and Django

Note

The following listing summarizes what is tested during development, using GitHub Actions as a CI environment.

You might be able to run in different environments and on different platforms (looking at you, macos).

Python is supported from version 3.7. Django is supported from version 3.1.

		Django
		3.1	3.2	4.0	4.1
Linux	3.7	supported	supported	not compatible [1]	not compatible [1]
	3.8	supported	supported	supported	supported
	3.9	supported	supported	supported	supported
	3.10	supported	supported	supported	supported
Windows	3.7	untested [2]	untested [2]	not compatible [1]	not compatible [1]
	3.8	untested [2]	untested [2]	untested [2]	supported
	3.9	supported	supported	supported	supported
	3.10	supported	supported	supported	supported

[1] (1,2,3,4)

This version of Python is not supported by this version of Django.

[2] (1,2,3,4,5)

This combination is not tested during CI, because the Python version does not ship with the required extension of SQLite to support JSON fields. However, installing the package is tested and working.

Note

Python 3.7 and 3.8 are not tested on Windows hosts, because these Python versions are not shipped with the required SQLite extension to handle JSON fields.

This is not relevant if you’re using another DB (Postgre, MariaDB).

See the Django wiki for a detailled walkthrough on how to activate the required extension to SQLite on Python 3.7 / 3.8 for Windows hosts.

django-calingen is assumed to run on Python 3.7 / 3.8 on Windows hosts.

Additional Python Packages

Besides Django, there is - as of now - only one additional dependency, namely python-dateutil. See requirements/common.txt for details.

Installation

django-calingen is installable from PyPI.

pip install django-calingen

Configuration

Project’s settings Module

Include 'calingen' into INSTALLED_APPS:

INSTALLED_APPS = [
  '...
  'calingen',  # <- added!
]

Note

While the Python package of the app is named django-calingen, the actual app is just named calingen.

This is common for pluggable Django applications

Please note that Layouts and Event Provider are provided as standalone apps and must be included in INSTALLED_APPS aswell. See the respective installation instructions.

It is assumed that the project is set up to look in applications directories for templates, as this is the default setting. Please refer to TEMPLATES.

Project’s urls Configuration

Include the app’s urls into the project’s url configuration:

from django.urls import include, path

urlpatterns = [
    ...
    path('calingen/', include('calingen.urls')),  # <- added!
]

App-specific Configuration Options

There are some configuration options, which can be set using the project’s settings module.

All of them are providing sane default values.

App-specific Settings has some more details on that topic.

Checks

django-calingen does provide some contributions to Django’s System check framework, basically to check app-specific configuration values. See calingen.checks for details.

Modify calingen’s Templates

django-calingen is developed to be as pluggable as possible. This means: there are basic templates included with the app, but these are mainly focused on development.

To actually deploy the app within a Django project, you will want to replace the app’s templates by overriding them.

Modify Templates provides additional information that should suffice as a starting point.