Ctrl+K

Development

Development#

Anyone is welcome to contribute to the code. To do so you must clone the content of this repository and install the library using the following command:

pip install -e .[tests]

This will install all requirements that are necessary for local development. It is best practice to create a new branch before adding any changes.

git checkout -b my-meaninful-branchname

After all changes have been committed and pushed back to the repository you can submit the merge request that will be reviewed by the slk team.

Code conventions#

The gitlab test pipeline performs format checking. To check if the code is still formatted correctly you can add a pre-commit hook that performs those checks every time you are about to commit changes to the code. To add the commit hook run the following command:

pre-commit install

Prepare and create a release#

run tests:

pytest -v tests

check codestyle:

flake8 pyslk
black --check -t py310 pyslk
isort --check --profile black pyslk

make a release for PyPI (example for version 2.0.1):

vim CHANGES.md         # update changes for the new version (for GitLab Repo Readme)
vim doc/changelog.rst  # update changes for the new version (for online documentation)
# increment version number from 2.0.0 to 2.0.1
sed -i 's/2\.0\.1/2.0.2/g' doc/development.rst README.md
sed -i 's/2\.0\.0/2.0.1/g' pyproject.toml meta.yaml doc/availability.rst doc/development.rst README.md
# manually imcrement the 'sed' expressions from the lines above in README.md and doc/development.rst
vim README.MD
vim doc/development.rst
# set tag and commit in git
git tag 2.0.1        # tag version
git commit -a        # commit changes
git push --tags      # push changes including tag
git push             # push changes
python -m pip install build
python -m build . --sdist
# twine upload dist/pyslk-2.0.1.tar.gz     # upload to pypi (currently not done)

make a conda package (example for version 2.0.1):

vim CHANGES.md         # update changes for the new version
vim pyproject.toml     # update version number
vim meta.yaml          # update version number
conda-build .          # build conda packages
mkdir conda            # create folder to move conda packages to
# move conda packages
cp /opt/python/anaconda3/conda-bld/linux-64/pyslk-2.0.1-py39_0.tar.bz2 conda/
cp /opt/python/anaconda3/conda-bld/linux-64/pyslk-2.0.1-py310_0.tar.bz2 conda/
cp /opt/python/anaconda3/conda-bld/linux-64/pyslk-2.0.1-py311_0.tar.bz2 conda/

update documentation for new version (example for version 2.0.1):

vim doc/changelog.rst       # update changes for the new version
vim doc/availability.rst    # replace old version string in the filenames of the pyslk packages (6x times)

Generate documentation#

# install needed dependencies for doc generation
pip3 install -U mock sphinx-book-theme numpydoc
# install this package without dependencies
pip3 install --no-deps -e .
# If dependencies are missing, please check whether all dependencies, which are listed in section
# `project.optional-dependencies` under `doc`, are also installed here. I dependencies are missing here, please add
# them.

# Generate `pyslk.rst` and `modules.rst` files which contain only `:orphan:`. These files will be ignored by Sphinx
# during the generation of the documentation. If they would not exist, sphinx-autodoc would generate them/
if [ ! -e doc/pyslk.rst ]; then echo ":orphan:" > doc/pyslk.rst; fi
if [ ! -e doc/modules.rst ]; then echo ":orphan:" > doc/modules.rst; fi
# Prepare doc generation
sphinx-apidoc -o doc pyslk
# Generate documentation
sphinx-build -b html doc build/html
# you will find the documentation in `./build/html/index.txt`

Note

Before generating the documentation the first time, the doc/conf.py was edited as follows: sys.path.insert(0, os.path.abspath(‘..’)) was set and ‘sphinx.ext.autodoc’ was inserted in the list extensions.

Contents