Skip to main content
Warning This document has not been updated for a while now. It may be out of date.
Last updated: 9 Sep 2021

govuk-data-science-workshop: `govuk-data-science-workshop` structure

This page provides information on the repository's structure. The repository's folder structure is explained here:

:maxdepth: 2
./data.md
./docs.md
./notebooks.md
./outputs.md
./src.md
./tests.md

Top-level files

Each subsection here contains a brief description about the files at the top-level of this Git repository.

.envrc

A file containing environment variables for the Git repository that can be selectively loaded. .envrc uses the direnv shell extension to load these environment variables.

This file contains a sed command to output a .env file with all the environment variables. This may be useful for sourcing environment variables, for example in conjunction with PyCharm's EnvFile plugin.

To ensure this sed command works correctly, make sure any file paths listed in this file are absolute file paths (recommended). Relative file paths using other environment variables only work for Python users. Environment variable names can only contain letters, numbers or underscores as well. For example:

export DIR_DATA=$(pwd)/data                    # fine for Python and R users
export DIR_DATA_EXTERNAL=$(pwd)/data/external  # fine for Python and R users
export DIR_DATA_EXTERNAL=./data/external       # fine for Python and R users
export DIR_DATA_EXTERNAL=$DIR_DATA/external    # fine for Python users only
export DIR-DATA-EXTERNAL=$DIR_DATA/external    # will break the `sed` command!

.flake8

A configuration file for the flake8 Python package that provides linting. This file is based on the common configuration described in the GDS Way.

.gitignore

A .gitignore file to ignore certain files and folders from this Git repository. See the contributor guide to modift the .gitignore file.

.pre-commit-config.yaml

A pre-commit hook configuration file.

.secrets

A file to store all secrets and credentials as environment variables. This file is read-in by .envrc, when loading environment variables with the direnv shell extension, but is not tracked by Git.

.secrets.baseline

Baseline file for the detect-secrets to detect secrets. In conjunction with pre-commit, detect-secrets prevents secrets from being committed to the repository. The baseline file flags secret-like data that the user deliberately wishes to commit the to repository.

CODE_OF_CONDUCT.md

The Code of Conduct for contributors to this project, including maintainers and alphagov organisation owners.

conftest.py

File to contain shared fixture functions for the pytest tests in the tests folder.

CONTRIBUTING.md

The contributing guidelines for this project.

LICENSE

The licence for this project. Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.

Makefile

The Makefile contains a set of commands for the make utility. Run the help command for further information at the top-level of the Git repository.

make help

pyproject.toml

A file containing Python project settings. This includes configuration settings for:

isort

Python imports are arranged according to the specification defined by black.

pytest

To run the tests within the tests folder using the pytest Python package, enter the following command:

pytest

Code coverage

To run code coverage using the coverage Python package with pytest, enter the following command:

coverage run -m pytest
coverage html

or using the make command:

make coverage_html

A code coverage report in HTML will be produced on the code in the src folder. This HTML report can be accessed at htmlcov/index.html.

README.md

An overview of the Git repository, including all necessary instructions to run the code.

requirements.txt

A list of Python package requirements for this Git repository, which can be installed using the pip install command.

pip install --requirement requirements.txt

Alternatively, to install the requirements file along with pre-commit hooks, run the following command:

make requirements