Package Guide

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 update
sudo apt-get install -y --no-install-recommends \
 python3-pip \
 libcairo2-dev \
 libfreetype6-dev \
 libffi-dev \
 libjpeg-dev \
 libpng-dev \
 libz-dev
pip install --upgrade pip
pip install --user -r requirements.txt

Building

Building this package requires 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 .
echo "Running pydocstyle"
pydocstyle --count .

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

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/run_local_tests.sh

Change the python version by setting the environment variable PYTHON_V_ONLY

./tests/run_local_tests.sh -e PYTHON_V_ONLY="3.10"

Python 3.x, 3.8, 3.9, 3.10, 3.11 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
 RUN python3 -m pip install --upgrade pip
 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.8"
 docker_run_integration_tests "3.9"
 docker_run_integration_tests "3.10"
 docker_run_integration_tests "3.11"
fi

VSCode

This package includes a preconfigured Visual Studio Code (VSCode) workspace and development container, making it easier to get started with developing your plugin.

To get started with developing your plugin in VSCode, follow these steps:

Open the project in VSCode Open VSCode and select the "Open Folder" option from the File menu. Navigate to the location where you've saved the project and select the root folder of the project.
Connect to the development container VSCode will automatically detect the presence of the development container and prompt you to connect to it. Follow the on-screen instructions to connect to the container.
Run the build task To build the plugin, you can use the preconfigured build task in VSCode. This task is defined in the build.sh file and can be run by using the "Run Build Task" option from the Terminal menu or by using the Ctrl + Shift + B shortcut.
Debug the plugin You can use the VSCode debugger to inspect the code and debug your plugin. The debugger is configured in the launch.json file and can be started by using the "Start Debugging" option from the Debug menu or by using the F5 key.

For more information on how to use VSCode and Docker for development, please refer to how I develop with VSCode and Docker and how I use VSCode tasks.

Packaging

The project uses Hatch to build and package the plugin

Hatch is a Python packaging tool that helps simplify the process of building and distributing Python packages. It automates many manual steps, such as creating a setup script, creating a distribution package, and uploading the package to a repository, allowing developers to focus on writing code. Hatch is flexible and customizable, with options for specifying dependencies, including additional files, and setting up test suites, and is actively maintained with a growing community of users and contributors.

Build the package

hatch build

Publish the package

hatch publish

Please note that you may need to set up the appropriate credentials for the repository before you can publish the package. If you encounter any issues with publishing the package, please refer to the Hatch documentation for guidance.

Last update: August 25, 2023