Structure

Package Structure

The package structure is outlined below and serves as a guideline for those providing competing and/or complementary features.

Project/                         # Project/Repsoitory root
 templates/                      # Namespace reserved for web-templates
  django/                        # Namespace reserved for Django templates
    templates/skeleton.html      # Django skeleton template
  flask/                         # Namespace reserved for Flask templates
  tornado/                       # Namespace reserved for Tornado templates
  sphinx/                        # Namespace reserved for sphinx templates
  django.html                    # Reserved name for a Django template engine template
  jinja.html                     # Reserved name for a Jinja/Jinja2 template
 setup.py                        # Setup.py script that bundles everything together
 MANIFEST.in                     # Manifest file that embeds the various data sources into the distributed package.

This package reserves the package namespace templates.* by providing a namespaced package/folder with the the name templates in the project root. Furthermore the template names django.html and jinja.html are reserved for the base HTML templates used by the Django and Jinja templating systems respectively.

Note

Given the package/template path package/django/templates/skeleton.html one includes package.django within INSTALLED_APPLICATIONS and extends skeleton.html within their base.html template. Django knows to look for the templates under the templates subfolder.

Structure limitations

The desired structure for the core of the package is as follows

project\
 templates\
  django\templates\skeleton.html # Combines base.structure.html and base.html into a single file, currently available as
  sphinx\templates\skeleton.html # Combines `base.sphinx.html`, `basic.layout.html` and `basic.layout - copy.html` into a single file
  jinja\templates\skeleton.html  # Combines `base.jinja.html` into a single file

Previously the following alternatives have been attempted but they fail for various reasons.

templates\ base.html __init__.py	templates\ templates\base.html __init__.py
Unpackageable	Makes template into an explicit package

Django expects that a templates folder exists containing the templates. In the first structure Django simply ignores the base.html as a result. In the second case Django finds the file as appropriate but it does not like the fact that the root package is namespaced. The work around is to nest the package one level deeper to appease Django and get the user to list templates.django under their INSTALLED_APPS in their settings.py file.

Artefacts

The following templates are the leftovers from prior development attempts.

basic/              Additional Sphinx related templates (Not sure on status or usage)
 layout.html        This embeds the jinja2 tags expected by sphinx within the django template tags (not sure how this differs from base.sphinx.html).
base.django.html    The django base template as prescribed by modern HTML5; Originally base.structure.html
base.sphinx.html    This is adapted from base.structure.html to accomodate Sphinx projects.
base.jinja.html     This is adapted from base.structure to accomodate jinja as the template engine.
base.html           This is adapted from base.structure to accomodate JavaScript libraries, this needs more work i.e. selectively enabling one or another library.

For the most part these are to be deprecated/deleted but there is still some value to extracted before doing so. The templates under the basic should really be merged/compared against the base.sphinx,html file for instance as this has allowed me to embed sphinx documentation within a Django site before for instance.