Dev Setup

This page include notes for continued development of the library, on aspects such as package management, documentations and unit testing.

Poetry

Poetry is used for managing pip packages and the build and publish of cvpl_tools into PyPI. However, I find Poetry slow adding dependencies as it needs to search over versions of packages in resolving dependencies and generating lock file. In local development, I use an Anaconda environment to install the same list of packages in pyproject.toml

Building and publishing the package to PyPI is done with the appropriate setup followed by running poetry build and poetry publish.

The steps is as follows:

  1. Modify your codebase

  2. Modify the version string in pyproject.toml

  3. Run poetry build then poetry publish

Documentations

The documentation of cvpl_tools has two aspects: within-source and on-line. In the source code, the library uses the convention that every API function includes a Python docstring in Google Style and also include comments when suitable at the start of a source code file.

Related to Numpy: Numpy has a numpy.typing module which allows documenting the APIs with Numpy typing hint such as np.typing.NDArray[np.float32] representing an array of type float. This module requires mypy package, with configuration file at “cvpl_tools/mypy.ini”.

The on-line documentation locates at “cvpl_tools/docs” folder, which is a sphinx documentation that can be built using the command:

cd docs
sphinx-build -M html . ./_build

The “docs” folder includes a “conf.py” file which imports the source code under “src” to support the “autoclass” and “autofunction” directives used in the documentations.

The diagrams in “docs/assets” are generated using the diagram editor Dia, which is an open source software good for drawing programming diagrams.

Unit Testing

pytest is used for unit testing. Run unit tests with pytest test command in the root directory. Configuration file is at “cvpl_tools/pytest.ini”.

Misc

  • I use PyCharm as my development IDE

  • The on-line documentation is hosted by Github Pages, which you can see the setting on GitHub by first go to the main GitHub page then visit Settings > Pages.