Developing

You can clone the repository with

git clone https://code.studioinfinity.org/glen/mkdocs-semiliterate

For the remaining steps, it may be easiest to do them in a python virtual environment. If you put the virtual environment in .venv at the top level of the project, it will not disrupt any of the tests. Remember to activate your virtual environment before doing the testing. You can build the distribution with

 pip install build
 python -m build .

That will produce a .whl file in the dist subdirectory.

Testing

If you have a Docker daemon running on your local machine and the Drone command-line installed, you can run all of the tests via drone exec. If not, or if you don’t want to wait for the Docker container to spin up and install all of the prerequisites, you can make sure you have the version of mkdocs-semiliterate that you want to test currently properly installed in the python you are currently running, and then starting from the top-level mkdocs-semiliterate directory, run the commands that drone uses to test:

 flake8 --max-line-length=80 --extend-exclude=build --extend-exclude=.venv
 mkdocs build
 find site -not -path '*fonts*' -not -path '*img*' -not -path '*js*' | sort -f | diff tests/bootstrap.manifest -
 bash tests/sites.bash

All of the commands should succeed and none of the diffs should produce any output.

Contributing

You can report issues at the repository site. Pull requests are welcome as well. If you’re new to contributing to open-source projects, mkdocs-simple-plugin has a very nice tutorial.

Publishing

This package is published to PyPI using twine. Mostly to jog the developer’s memory, when a new release is freshly built, the command to update PyPI is twine upload dist/*. Also don’t forget to create a fresh release on the repository site as well. Finally, you can manually upload the new doc pages for mkdocs-semiliterate itself so the pages can be served by moving the newly-produced site directory to semiliterate and then executing

scp -r -i [IDENTITY_FILE] semiliterate [USER]@[SERVER]:/opt/bitnami/apps/wordpress/htdocs