Skip to content

Documentation

This site uses MkDocs to build its documentation and GitHub Pages for hosting.

Format

Documentation within this project follows the following pattern:

  • A README.md for each component
  • A /docs folder for the project

Each README.md should contain:

  • A description of what the component is/does
  • A list of any prerequisites
  • Setup instructions
  • Execution instructions
  • Deployment instructions

The /docs folder should contain:

  • A description of what the project is
  • An overview of how the everything fits together in the project
  • An explanation of the tech stack
  • Details of the underlying dataset

A majority of the information should reside within the /docs directory over the README. The READMEs in this project should be kept for concise instructions on how to use each component. Any detailed explanation should be kept within /docs.

Getting MkDocs Setup

In order to build an MkDocs deployment or serve the documentation locally, we need to install MkDocs and its dependencies.

  1. Navigate into the project's root directory.

  2. Install MkDocs and its dependencies.

    pip install -r mkdocs_requirements.txt

  3. You can now use MkDocs. To see a list of commands run the following:

    mkdocs --help

Please Note: Python's package manager, PIP, is required to install MkDocs. Please make sure you have Python installed beforehand.

Updating MkDocs Deployment

If changes are made within /docs, the GitHub Pages deployment will need to be updated. Assuming you have already installed MkDocs and Material for MkDocs, do the following:

  1. Navigate to the projects root directory.

  2. Delete the existing /mkdocs_deployment directory.

  3. Build the MkDocs deployment.

mkdocs build

  1. Rename the /site directory to /mkdocs_deployment. This allows git to track the build so GitHub Pages can redeploy it.

  2. Commit and Push changes.

Once completed, a GitHub Action will redeploy the new build to GitHub Pages.