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 using mkdocs_simple_gen to generate the site.

mkdocs_simple_gen --build -- --verbose

Testing

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

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

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

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 .
echo "Running pydocstyle"
pydocstyle --count .

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.