Developer documentation¶
Welcome to the developer documentation of the pymetacode package. Unlike the API documentation, this part gives some general background information for developers who want to actively contribute to the project.
Virtual environment¶
The whole development should take place inside a virtual python environment that should be located outside the project directory.
To create a new virtual python environment, open a terminal and change to a a directory where the virtual environment should reside. Then type something like:
virtualenv pymetacode
or alternatively:
python3 -m venv pymetacode
This will create a virtual environment in the directory “pymetacode”. To activate this virtual environment, use:
source pymetacode/bin/activate
To deactivate, the command would simply be:
deactivate
Autoincrementing version numbers¶
The version number is contained in the file VERSION in the project root directory. To automatically increment the version number with every commit, use a git hook that calls the file bin/incrementVersion.sh. Git hooks reside in the directory .git/hooks. The simplest would be to create a new file pre-commit in this directory with the following content:
#!/bin/sh
./bin/incrementVersion.sh
Make sure to set it to executable and have a line break (aka: new or empty line) at the end of the file. Otherwise, you man run into trouble, i.e., not having your version number updated automatically with each commit.
Directory layout¶
The pymetacode package follows good practice of the Python community regarding directory layout. As there will be several subpackages available, these reside each in a separate directory containing its own __init__.py file. All packages/modules reside below the pymetacode directory of the project root. The tests directory follows the same structure and contains all the module tests. Generally, the pymetacode package should be developed test-driven (test-first) as much as possible.
(This) documentation resides inside the docs directory of the project root. The auto-generated API documentation is in its own directory.
A general overview of the overall package structure:
bin/
pymetacode/
docs/
api/
tests/
Code formatting¶
Generally, code formatting follows PEP 8 guidelines. Given that PySide does not follow these guidelines in several aspects, this leads to mixing different conventions. However, whenever own code is concerned, stick to the PEP 8 guidelines.
A consistent code formatting is enforced using Black, with the only change to the default settings being the line width of 78 characters (as compared to the standard of 88 characters). Use black -l 78 on the command line, or, preferably, configure Black in your IDE. For PyCharm (starting with 2023.2), the settings can be found in Preferences | Settings > Tools > Black. Here, set -l 78 as command-line options via the Settings edit field. For older PyCharm versions or other IDEs/editors see the official Black documentation.
To use Black, it needs to be installed. Either install it separately
pip install black
or install the pymetacode package with the appropriate dependencies:
pip install pymetacode[dev]
In case you are installing the pymetacode package in editable fashion (as usual for development purposes), use the following command from within the package directory (i.e., the one containing the setup.py file):
pip install -e .[dev]
To automatically format your Python code with every commit, use a git hook that calls the file bin/formatPythonFile.sh. Git hooks reside in the directory .git/hooks. The simplest would be to create a new file pre-commit with/add to the existing file in this directory the following content:
./bin/formatPythonFile.sh
For static code analysis using Prospector, see the respective section.
Docstring format¶
The Docstring format used within the code of the pymetacode package is “NumPy”. For convenience, set your IDE accordingly.
For PyCharm, the settings can be found in Preferences > Tools > Python Integrated Tools. Here, you find a section “Docstrings” where you can select the Docstring format from a number of different formats.
Unittests and test driven development¶
Developing the pymetacode package code should be done test-driven wherever possible. The tests reside in the tests directory in the respective subpackage directory (see above).
Tests should be written using the Python unittest framework. Make sure that tests are independent of the respective local environment and clean up afterwards (using appropriate teardown methods).
Setting up the documentation build system¶
The documentation is built using Sphinx, Python. Building requires using a shell, for example bash.
To install the necessary Python dependencies, create a virtual environment, e.g., with virtualenv <environment>, and activate it afterwards with <environment>/bin/activate. Then install the dependencies using pip:
pip install sphinx
pip install sphinx-rtd-theme
pip install sphinx-multiversion
Alternatively, you may simply install pymetacode with the required dependencies:
pip install pymetacode[docs]
In case you are installing the pymetacode package in editable fashion (as usual for development purposes), use the following command from within the package directory (i.e., the one containing the setup.py file):
pip install -e .[docs]
To build the documentation:
Activate the virtual environment where the necessary dependencies are installed in.
cdtodocs/, then runmake html. (To clean previously built documentation, runmake cleanfirst).
To build the documentation for all releases and the current master branch:
Activate the virtual environment where the necessary dependencies are installed in.
cdtodocs/, then runmake multiversion. (To clean previously built documentation, runmake cleanfirst).
Static code analysis with Prospector¶
Static code analysis can be performed using Prospector. First, install the necessary tools into the virtual environment created for the pymetacode package:
pip install prospector[with_pyroma]
The optional arguments ensure that all necessary dependencies are installed as well.
Alternatively, you may simply install pymetacode with the relevant dependencies:
pip install pymetacode[dev]
The optional arguments ensure that all necessary dependencies are installed as well.
Afterwards, simply run Prospector from a terminal from within your project root:
prospector
It will display the results of the static code analysis within the terminal. Settings can be changed in the .prospector.yaml file in the project root, but please be very careful changing settings here. Often, it is better to (temporarily) silence warnings in the code itself.