Overview¶
This project uses Python 3.6 Django 2.2+, Django Crispy Forms 1.9+ for basic
development. The basic package requirements can be found in setup.cfg
and
everything needed for development is listed in requirements.txt
. The demo
site is handy for debugging so you will need to install nvm to manage node
versions/
Layout¶
The package follows the recommendations made by Ionel Mărieș and puts the
source code for the package in the src
directory. That does make life
slightly complicated regarding the PYTHONPATH
but that’s easily overcome
with the project’s makefile.
Makefile¶
The project has a Makefile
that contains a number of targets to make life
easy. You can read a brief description by running make
on the command line:
make
Demo¶
The project contains a Demo site to show that the various Design System components
work as expected. It’s a full Django site so it’s good for debugging and generally
mucking around. The Makefile
has targets for building the all the assets:
make clean-frontend
make frontend
The target for running the demo site takes care of building all the assets:
make serve
The demo uses webpack to assemble everything. That gives you two options when building the assets manually:
Build into a single JavaScript file for use running the demo site:
nvm use npm run dev
Build into separate JavaScript and CSS files, minified for deployment:
nvm use npm run build
Generally the dev version is sufficient. Ideally you should not rely on this project for building the assets for production. You might find the webpack config file handy for getting started with your own version however.
Running tests¶
You can run the tests for an individual test case, the entire suite or for all the supported versions of python and Django.
Run a specific set of tests, for example:
PYTHONPATH=src pytest tests/layout/test_accordion
The
PYTHONPATH
needs to be set because of the way the source code is laid out.
Run the entire test suite:
make tests
This is just the equivalent of
PYTHONPATH=src pytest
.
Run the entire test suite for all versions:
tox
A summary coverage report will be printed to the console, with an HTML report at
htmlcov/index.html
.
Development standards¶
This project uses black, flake8 and isort to enforce consistent python styles. Plugins
for each are added to pytest
to keep you honest. You can also run black and isort on
the command line to reformat your code in one go:
black src
isort -rc src
Generally it’s better to use editor plugins to make the changes whenever a file is saved.
Documentation¶
The documentation uses sphinx and doc8. The makefile has handy targets for building the sphinx docs:
make clean-docs
make docs
You can check your penmanship from the command line:
doc8 docs