Developing

Prerequisites

You will need to have MKDocs installed on your system. I recommend installing it via pip to get the latest version.

sudo apt-get install python-pip
pip install --upgrade pip --user
pip install -r requirements.txt
pip install -e .

Building

Building this package requires generating the readme files for the examples.

./examples/gen_readme.py

And then using mkdocs_simple_gen to generate the site.

mkdocs_simple_gen --build -- --verbose

Testing

Lint

Linting helps maintain style consistency. This package follows the google style guide. Conformity is enforced with flake8 and pydodstyle.

./tests/run_linters.sh

Code

echo "Running flake8 linter -------->"
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics --exclude=setup.py
flake8 . --count --exit-zero --max-complexity=10 --max-line-length=80 --statistics --exclude=setup.py

echo "Running pydocstyle"
pydocstyle --count --convention=google --add-ignore=D415,D107 .

Different Python versions

You can even test the package with different versions of python in a container by running the test_local script. This builds a docker container with the version of python you specify and runs the integration tests within the container.

./tests/test_local.sh

Python 3.x, 3.7, 3.8, 3.9, 3.10 supported.

Code

set -e

End-to-end testing via Bats (Bash automated tests)
function docker_run_integration_tests() {
docker build -t mkdocs-simple-test-runner:$1 -f- . <<EOF
FROM python:$1
RUN apt-get -y update && apt-get -y install bats gcc sudo
COPY . /workspace
WORKDIR /workspace
EOF

echo "Running E2E tests via Bats in Docker (python:$1) -------->"
docker run --rm -it mkdocs-simple-test-runner:$1 tests/run_unit_tests.sh
docker run --rm -it mkdocs-simple-test-runner:$1 tests/run_linters.sh
docker run --rm -it mkdocs-simple-test-runner:$1 tests/run_integration_tests.sh
}

if [[ ! -z "$PYTHON_V_ONLY" ]]; then
echo "only v $PYTHON_V_ONLY"
docker_run_integration_tests "$PYTHON_V_ONLY"
else
docker_run_integration_tests "3"
docker_run_integration_tests "3.7"
docker_run_integration_tests "3.8"
docker_run_integration_tests "3.9"
docker_run_integration_tests "3.10"
fi

Unit tests

Unit tests help ensure individual functions perform as expected. Unit tests in this module use the the standard python unittest framework.

./tests/run_unit_tests.sh

Code

python3 -m unittest tests/test_*.py

Integration tests

Integration testing allows the plugin to be tested with mkdocs using example configurations.

Integration testing uses bats, install it with

sudo apt-get install bats

Then run the tests

./tests/run_integration_tests.sh

Code

./examples/gen_readme.py
./tests/integration_test.bats

VSCode

Included in this package is a VSCode workspace and development container. See how I develop with VSCode and Docker and how I use VSCode tasks.