Metadata-Version: 2.1
Name: texsite
Version: 4.3.0
Summary: texsite delivers great and ready-to-use page templates for Wagtail CMS
Home-page: https://gitlab.com/texperience/texsite
Author: Timo Rieber
Author-email: trieber@texperience.de
License: ISC License (ISCL)
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Wagtail
Classifier: Framework :: Wagtail :: 4
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django <3.3,>=3.2
Requires-Dist: django-bootstrap-ui <3.0,>=2.0
Requires-Dist: wagtail <4.2,>=4.1
Provides-Extra: development
Requires-Dist: brunette <1.0,>=0.2 ; extra == 'development'
Requires-Dist: flake8 <7.0,>=6.0 ; extra == 'development'
Requires-Dist: isort <6.0,>=5.11 ; extra == 'development'
Requires-Dist: coverage <8.0,>=7.1 ; extra == 'development'
Requires-Dist: tox <4.0,>=3.28 ; extra == 'development'
Provides-Extra: linting
Requires-Dist: brunette <1.0,>=0.2 ; extra == 'linting'
Requires-Dist: flake8 <7.0,>=6.0 ; extra == 'linting'
Requires-Dist: isort <6.0,>=5.11 ; extra == 'linting'
Provides-Extra: testing
Requires-Dist: coverage <8.0,>=7.1 ; extra == 'testing'
Requires-Dist: tox <4.0,>=3.28 ; extra == 'testing'

# texsite

[![Pipeline][pipeline-badge]][pipeline-link]
[![Coverage][coverage-badge]][coverage-link]
[![PyPI][pypi-badge]][pypi-link]
[![License][license-badge]][license-link]

[pipeline-badge]: https://gitlab.com/texperience/texsite/badges/master/pipeline.svg
[pipeline-link]: https://gitlab.com/texperience/texsite/pipelines
[coverage-badge]: https://gitlab.com/texperience/texsite/badges/master/coverage.svg
[coverage-link]: https://gitlab.com/texperience/texsite/-/jobs
[pypi-badge]: https://img.shields.io/pypi/v/texsite.svg
[pypi-link]: https://pypi.python.org/pypi/texsite
[license-badge]: https://img.shields.io/pypi/l/texsite.svg
[license-link]: http://en.wikipedia.org/wiki/ISC_license

texsite delivers great and ready-to-use page templates for the modern, flexible and user-focused web content management system [Wagtail CMS][wagtail] backed by the popular [Django web framework][django], both written in [Python][python].

Based on the amazing [StreamField][wagtail-streamfield] introduced with Wagtail release 1.0, which texsite uses extensively, it has never been easier for editors to author awesome pages. Read more on how this concept works in the great blog article [Rich text fields and faster horses][wagtail-rtfafh] written by Matt Westcott, lead technical developer of Wagtail.

[wagtail]: https://wagtail.io/
[django]: https://www.djangoproject.com/
[python]: https://www.python.org/
[wagtail-streamfield]: http://docs.wagtail.io/en/stable/topics/streamfield.html
[wagtail-rtfafh]: https://torchbox.com/blog/rich-text-fields-and-faster-horses/

## Features

* Clean Blog Pages - based on the [Clean Blog][startbootstrap-cleanblog] theme by Start Bootstrap
* Business Casual Pages - based on the [Business Casual][startbootstrap-businesscasual] theme by Start Bootstrap
* Outstanding test coverage
* Continuously integrated codebase

[startbootstrap-cleanblog]: https://startbootstrap.com/template-overviews/clean-blog/
[startbootstrap-businesscasual]: https://startbootstrap.com/template-overviews/business-casual/

## Technical requirements

New feature releases frequently add support for newer versions of underlying technologies and drop support for older ones. The compatible versions of Wagtail, Django and Python for each texsite release are:

| Release | Wagtail  | Django   | Python               |
|---------|----------|----------|----------------------|
| 4.0+    | 4.1 LTS  | 3.2 LTS  | 3.8, 3.9, 3.10, 3.11 |
| 3.0     | 2.11 LTS | 3.1      | 3.8                  |
| 2.0     | 2.7 LTS  | 2.2 LTS  | 3.6, 3.7, 3.8        |
| 1.0     | 2.3 LTS  | 1.11 LTS | 3.4. 3.5, 3.6        |

## Code and contribution

The code is open source and released under the [ISC License (ISCL)][isc-license]. It is available on [Gitlab][gitlab] and follows the guidelines about [Semantic Versioning][semver] for transparency within the release cycle and backward compatibility whenever possible.

All contributions are welcome, whether bug reports, code contributions and reviews, documentation or feature requests.

If you're a developer, fork the repo and prepare a merge request:

```bash
# Prepare your environment the first time
python3.8 venv ~/virtualenvs/texsite-py38
pip install -e .[development]

# Running the tests while development
python manage.py test --settings=tests.settings

# Individual supported versions tests and code quality checks
tox -e py38-dj22-wt27
tox -e isort
tox -e brunette
tox -e flake8

# Ensure code quality running the entire test suite,
# this requires all supported Python releases to be installed
tox
```

[isc-license]: http://en.wikipedia.org/wiki/ISC_license
[semver]: http://semver.org/
[gitlab]: https://gitlab.com/texperience/texsite

## Installation

Install `texsite` directly from [PyPI][pypi] using pip:

```bash
pip install texsite
```

[pypi]: https://pypi.org/project/texsite/

## Configuration

### Environment

The tool only requires one environment variable to work properly:

* `TEXSITE_DATA_ROOT`

This path is used to store:

* Uploaded user content such as images and documents
* Collected static files for the web application frontend
* Environment specific application configuration

For example set this environment variable in a bash to a valid directory path:

```bash
export TEXSITE_DATA_ROOT="$HOME/data/texsite"
```

### Django settings

On startup the application loads a module `localsettings` where you may provide environment specific Django settings, e.g. a database service.

It searches with the `sys.path` and first adds the path configured in the environment variable `TEXSITE_DATA_ROOT`.

## Docker

We provide production-ready Docker images for our entrypoints.

### Tags

The images are built using our [GitLab pipelines][pipeline-link] and hosted within a public [GitLab container registry][container-registry]. Our established pipeline recipe (borrowed from [callr][container-recipe]) ensures

* the `latest` tag is up-to-date with the `master` branch and
* every Git tag (e.g. `v4.1.0`) has also a corresponding Docker image tag.

### Images

The following images are available:

* `texsite/cli`: use the Django and Wagtail management commands (`django-admin`)
* `texsite/web`: serve the Django WSGI application (without serving static and media files)

### Usage

For the command line interface simply prepend the `docker run` command and its options before regular `django-admin` commands:

```bash
# Prepend `docker run` and its options
docker run \
  --name texsite-cli \
  --rm \
  --interactive \
  --tty \
  --env DJANGO_SETTINGS_MODULE=texsite.settings.[dev | production] \
  --env TEXSITE_DATA_ROOT=/texsite-data-root \
  --volume ~/data/texsite:/texsite-data-root \
  texsite/cli \
  # Use regular Django management commands
  [collectstatic | createsuperuser | migrate | ...]
  --settings=texsite.settings.[dev | production]
```

The web application image runs the Django WSGI application using `gunicorn` as application server. It can be launched as follows:

```bash
docker run \
  --name texsite-web \
  --rm \
  --detach \
  --env DJANGO_SETTINGS_MODULE=texsite.settings.[dev | production] \
  --env TEXSITE_DATA_ROOT=/texsite-data-root \
  --volume ~/data/texsite:/texsite-data-root \
  --publish 5000:5000 \
  texsite/web
```

### Compose
For local testing and development purposes a predefined Docker compose file is available.

After code changes the images have to be rebuilt with `docker compose build`.

To start all services execute `docker compose up --detach --remove-orphans` after adapting the compose volumes to your local environment. This runs the following containers:

* our texsite WSGI application
* a nginx webserver serving static files and acting as reverse proxy for the application

In addition you can easily use the `texsite-cli` container executing Django and Wagtail management commands:

```bash
docker compose run --rm --publish 8000:8000 texsite-cli runserver 0.0.0.0:8000
docker compose run --rm texsite-cli migrate
docker compose run --rm texsite-cli createsuperuser
docker compose run --rm texsite-cli collectstatic
```

[container-registry]: https://gitlab.com/texperience/texsite/container_registry
[container-recipe]: https://blog.callr.tech/building-docker-images-with-gitlab-ci-best-practices/
