Skip to content

Setting Up

We'll kick off by setting up your local development environment.

Important

If you have any questions about setting up your development environment for these SOPs, or you get stuck - feel free to reach out to the Operations Team.

Requirements

To contribute, you'll need the following -

Lets get cracking!

  • Fork and Clone the - SOPs Project - Guide.
  • Install the following Python packages: mkdocs-material, mkdocs-git-revision-date-localized-plugin, mkdocs-awesome-pages-plugin and mkdocs-redirects.

Easy Python Package Installation

These packages can be installed easily through a single command.

  pip install -r requirements.txt

You'll still need to ensure you have Python installed first, as these use pip - a Python package installer.

  • Once you've installed the requirements, open a command line terminal, cd into the cloned repository and start the mkdocs service:

mkdocs serve
OR 
python -m mkdocs serve

  • You'll see the command line performing some magic, eventually displaying Serving on http://127.0.0.1:8000. Open up your web browser, and navigate to that address.

Common Setup Issues

'pip' Term not Recognised

When running the pip install -r requirements.txt command, you may receive an error preventing any packages from being installed. Check that Python is installed and accessible by typing python into a VS Code terminal. If necessary, the Windows Store will open and allow you to install the correct Python package. Restart VS Code before continuing.

Script installed 'Not on PATH'

After running the pip install -r requirements.txt command, some packages may produce yellow warnings, such as below:

"WARNING: The script watchmedo.exe is installed in 'C:\Users\username\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.10_qbz5n2kfra8p0\LocalCache\local-packages\Python310\Scripts' which is not on PATH. Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location."

Python is recognised but some scripts have been installed beyond the scope of the software. Update your Windows PATH variable to include the path indicated in the error.

Follow the steps here to update your Windows PATH variable. Restart VS Code before continuing.

Using MkDocs

MkDocs is the underlying tool that we use for our SOPs. It takes in Markdown files, and converts them to a static website on each save, which is then pumped into your browser upon an automatic reload.

We can also run mkdocs build to build a export the core HTML/CSS/JS that can be uploaded via FTP to the web.

Info

You won't need to run the mkdocs build command. This is automatically run as a part of the GitHub deployment workflow. If you do run this command, please make sure you delete the site folder that is generated in your base directory before committing your code.

Sometimes MkDocs wont like your changes, and may escape from the running serve instance. This is usually as a result of a broken .pages file. Just undo your changes and try again.