Notes to Webmasters¶
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
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
assetsdirectory and all
*/staticdirectories 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.
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
.coveragerc: A configuration file for the
coveragePython package, which is used generate test coverage data.
.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.
All configuration for Travis CI is contained in the
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
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.
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.