Technical documentation

Release management

New releases are created using Github release feature. First a release branch is created (e.g. release/v1.10.10). Then Github Actions are triggered which check if pip and deb packages are created correctly. In case some problems appear, necessary fixes are being made on release branch (or sub-branches). When all problems are solved, release branch is being merged into master branch. Then a new release is added together with appropriate tag being added to a master branch. Github actions will automatically trigger making and uploading of pip and deb packages, as well as relase assets.

Preparing pip package

Follow these steps to produce binary wheel package:

pip install -r requirements.txt
pip install wheel twine
python -m pymchelper.run --version
python setup.py bdist_wheel
twine check dist/*.whl

Wheel packages are automatically uploaded by github actions to PyPI server

Preparing deb package

Follow these steps to generate single-file executables for Linux using pyinstaller:

docker build --tag pymchelper .
docker run --volume `pwd`/dist:/app/dist pymchelper:latest pyinstaller convertmc.spec
docker run --volume `pwd`/dist:/app/dist pymchelper:latest pyinstaller runmc.spec
docker run --volume `pwd`/dist:/app/dist pymchelper:latest pyinstaller --add-data 'pymchelper/VERSION:pymchelper' --onefile --name plan2sobp pymchelper/utils/radiotherapy/plan.py
docker run --volume `pwd`/dist:/app/dist pymchelper:latest pyinstaller --add-data 'pymchelper/VERSION:pymchelper' --onefile --name mcscripter pymchelper/utils/mcscripter.py

Run some tests:

./dist/convertmc --version
docker run  -v `pwd`/dist:/test/ ubuntu:12.04 /test/convertmc --version

Generate debian packages for all binaries:

cd debian_packages
./generate_deb_packages.sh convertmc runmc plan2sobp mcscripter

Deb packages are automatically uploaded to APT repository hosted on Github Pages.

Preparing sphinx documentation

Sphinx documentation written reStructuredText format is stored in docs folder. It is being translated to the HTML format by Sphinx tool and automatically deployed to the Github Pages instance by Github Actions. For details see .github/workflows/release-pip.yml file, in particular docs job. To generate documentation locally use these commands:

pip install docs/requirements.txt
sphinx-build -j auto docs docs/_build