Notes to Webmasters

Repository Structure

The notable parts of the Troop 89 website repository are listed below:

$ tree -a -L 2 --dirsfirst
.
├── assets
│   ├── img
│   ├── scss
│   └── robots.txt
├── bin
├── docs
├── fixtures
├── requirements
│   ├── base.txt
│   ├── dev.txt
│   └── prod.txt
├── static
├── templates
│   ├── admin
│   ├── includes
├── troop89
│   ├── announcements
│   ├── auth
│   ├── date_range
│   ├── events
│   ├── flatpages
│   ├── json_ld
│   ├── settings
│   ├── trooporg
│   ├── __init__.py
│   ├── urls.py
│   └── wsgi.py
├── CONTRIBUTING.rst
├── demo.secrets.json
├── LICENSE
├── manage.py
├── README.rst
└── requirements.txt
├── .coveragerc
├── .secrets.json
├── .secrets.json.travis
├── .travis.yml

Briefly, the purpose of each file and directory is as follows:

  • assets: A directory containing the site-wide static files

    • scss: The site’s Sass stylesheets, which are describe to overall appearance of the site. These files are compiled to CSS before being served by the production server.
    • img: The static media and graphics used by the website.
    • robots.txt: A file that contains instructions for web crawlers, such as those used by Google and other search engines.
  • bin: A directory containing executable scripts to help manage the site.

  • docs: The root directory for the site’s Sphinx documentation.

  • fixture: A directory containing data fixtures for the site’s Django models.

  • requirements: A directory containing the site’s Python package dependencies, which can be installed using pip.

    • base.txt: Fundamental package requirements for both production and development
    • prod.txt: Production-only package requirements
    • dev.txt: Development-only package requirements, e.g. debug tools, test coverage
  • static: The root directory for servable static media. The assets directory and all */static directories are copied here to be served by the production server.

  • templates: The root directory for site-wide Django templates, such as the homepage and the error pages.

  • troop89: A Python package containing the site’s Django apps and configuration files

    • announcements: A Django app for troop announcements.
    • auth: A Django app for custom user authentication.
    • date_range: A helper app for creating models that can reason about ranges of dates.
    • events: A Django app for handling event creation and calendar display.
    • flatpages: A Django app for customized hierarchical flatpages.
    • json_ld: A helper app for rendering json-ld formatted structured data.
    • settings: A Python module for site settings.
    • trooporg: A Django app for troop organization (patrols, election terms, positions, etc).
    • __init__.py: The Python package file.
    • urls.py: The root url configuration.
    • wsgi.py: The WSGI application entry-point.
  • CONTRIBUTING.rst and README.rst: Files containing documentation for the site’s repository.

  • demon.secrets.json: A configuration file for jump-starting a new site instance for development.

  • LICENSE: The project license file (MPL-2.0).

  • manage.py: A Python script provided by Django for managing the site’s Django apps.

  • requirements.txt: A requirements file that references the production package dependencies. It is equivalent to requirements/prod.txt.

  • .coveragerc: A configuration file for the coverage Python package, which is used generate test coverage data.

  • .travis.yml and .secrets.json.travis: Configuration files for Travis-CI continuous integration.

  • .secrets.json: A configuration file for sensitive data, such as database passwords and encryption keys. This file is not kept in version control.

External Services

Travis CI

The Troop 89 website uses Travis CI for continuous integration. Documentation for Travis is available online, though you will likley never need to worry about changing the configuration.

All configuration for Travis CI is contained in the .travis.yml file.

Coveralls

The Troop 89 website uses Coveralls.io to display its code coverage data. Code coverage analysis is performed by the Python coverage package. If you have installed the development dependencies, you can generate a manual coverage report by running the following commands

$ coverage run manage.py test
$ coverage report

Documentation for coverage is available on coverage Read the Docs.

Coverage data is submitted to Coveralls.io by a Travis CI job phase. This step is handled by the coveralls-python package. Note that the coveralls API key is stored by Travis CI in an environment variable.

Uptime Robot

Uptime Robot periodically monitors the Troop 89 Website for server issues. Uptime statistics are available on the Troop 89 Website Public Status page.

Read the Docs

Documentation for the Troop 89 website is automatically built and published by ReadTheDocs.org. If you are not already, you can browse this documentation online through Read the Docs. Otherwise, you can manually build the documentation using Sphinx by running the following commands.

$ cd docs
$ make html

The documentation will then be available in _build/html. Open the index.html file in a browser to begin browsing the documentation.