This page contains an overview of instructions for people intending to develop PyPO. These include the contributor guidelines, but also guidelines on how to document contributions and how to test PyPO.

Contributor Guidelines

People wishing to contribute are more than welcome to do so. Contributions can be made by opening a pull request to the main repository from your own fork of PyPO. This is the so-called fork-and-branch workflow. Create a fork from the PyPO repository to your own profile, and clone:

git clone <URL-to-your-PyPO-fork>

Set the original repo as upstream:

git remote add upstream https://github.com/PyPO-dev/PyPO

add

__device__ __inline__ void add(float(&v1)[3], float(&v2)[3], float(&out)[3])

Definition GUtils.h:251

It is good practice to make a feature branch in which you can store your work:

git checkout -b <new-branch-name>

Then, when it is time to push the changes to the original repo, run:

git push origin <new-branch-name>

This should prompt Github to ask you to open a pull request to the orignial repository. Open the pull request, and the contribution will be reviewed. If it is accepted, the changes will be merged into the original main branch. After the merge, do not forget to synchronise your remote/local copy:

git checkout main
git pull upstream main
git push origin main

Then, the feature branch can be deleted:

git branch -d <new-branch-name>

git push --delete origin <new-branch-name>

Issues, Feauture Requests & Bugs

Issues, feature requests and bugs can be reported in the PyPO issue tracker. In addition to the online issue tracker in the git repo, we maintain a list of commonly encountered issues for quick reference.

Instructions For Developers

As mentioned in the contributor guidelines, contributions to PyPO are more than welcome. This section contains information on utilities put in place to make it easier to develop, as well as certain rules and practices for making PyPO easy to maintain.

It is assumed that you have forked the PyPO repository to a root directory, which we will call PyPO-dev for now.

Dev Install

Installing PyPO for development is very similar to general installation: Navigate to the cloned (and forked) PyPO repository and run:

pip install -e .

The "-e" flag tells pip to install PyPO in the actual "src/PyPO/" directory of the PyPO repository. This means that any changes to the Python source code are immediately reflected in the package imported through Python. For the C/C++/CUDA code, this is not true. These scripts need to be compiled into libraries again (which happens when the pip install -e . command is run) before the changes are reflected in the package.

PyPO can be uninstalled by running:

pip uninstall PyPO-pkg

Note that this does not remove the compiled libraries in the "src/PyPO/" folder. If desired, these need to be removed manually.

Generating Documentation

PyPO documentation is generated using Doxygen and generated from comment blocks. Because of this, there are several rules for developers regarding comments.

C/C++ And CUDA Source

The C/C++/CUDA scripts use the so-called Javadoc style for documenting classes and methods:

/**
   Here comes a short description describing in keywords what the function does
  
   Followed by a longer description, placing the function's usage in a broader perspective perhaps.
  
   @param input Some input parameter of type inputObject.
   @return output Some output parameter of type outputObject.
  
   @see inputObject
   @see outputObject
 */
outputObject someFunc(inputObject input) {
    ...
    return output;
}

In addition to properly documented classes and methods, each file should include a file description with an appropriate tag, so that doxygen can include the file in the full software documentation. The file description should be given after includes/preprocessor statements, but before the first class or method is declared:

<includes/preprocessor statements up here...>
 
/*! \file someFile.cpp
    \brief A brief description of the file.
 
    Here a longer description of this file should be placed.
*/
 
<rest of script down here...>

Python Source

The Python classes and methods are documented using docstrings with a slight twist, as Doxygen's special commands are not supported using pure docstrings. The trick to making doxygens special commands work with docstrings, is placing an exclamation mark right after the first triple double quotes:

def someFunc(inputObject):
    """!
    Here comes a short description describing in keywords what the function does
 
    Followed by a longer description, placing the function's usage in a broader perspective perhaps.
 
    @param input Some input parameter of type inputObject.
    @return output Some output parameter of type outputObject.
 
    @see inputObject
    @see outputObject
    """
    
    ...
    return output

The exclamation mark tells doxygen to parse the docstring as a doxygen documentation block. This allows doxygen to generate documentation, while also allowing the built-in help() function of Python to recognise the docstring, albeit with a lone "!" prepending the output of help().

File descriptions go on the top of the file:

"""!
@file
Here comes a brief description of the file.
 
If needed, provide a detailed description here.
"""
 
<import statements here...>
<rest of script down here...>

Again, adding these file descriptions is important, otherwise the file will not be parsed and added to the full software documentation. Tests are also supposed to carry a file description, but the test functions do not need a full documentation.

The "Templates.py" file containing templates for all used dictionary inputs is documented in the following style:

##
# Description of input dictionary
#
# @ingroup public_api_templates
dict = {
    "field1"    : "Description of field 1",
    "field2"    : "Description of field 2",
    ...
}

It is important to add the @ingroup public_api_templates command to the documentation block, as this puts the documentation on the right page in the final HTML output. Also, if you add a new input dictionary type, please document the meaning of each field in the demonstrated way.

Extra Reading

For an overview of the mentioned (and other) comment styles for doxygen, see this link.

Generating Documentation

The documentation can be generated using the GenerateDocs.py script:

python3 GenerateDocs.py

This will generate the full PyPO user manual and place it in the "docs/" directory. Note that this requires a full doxygen install. Please see their installation page for installation instructions.

Running The Automated Tests

Python

PyPO contains an automated testing suite that can be run quite easily from the command line using nose2. Note that, in order to run the unit tests, PyPO should be installed in development mode.

Navigate to the PyPO root directory and run:

nose2

This command will execute the entire testing suite.

Note that nose2 needs to be installed for this:

pip install nose2

Apart from running the test suite, it is also possible to generate a coverage report afterwards. For this, coverage needs to be installed in addition to nose2:

pip install coverage

The coverage report can then be generated by running:

nose2 --with-coverage

and the coverage report will be displayed in the terminal after running the tests.

If desired, further coverage info can be obtained by running:

coverage html

in the PyPO root directory. Then, in-depth coverage information can be viewed by running the index.html file in the htmlconv/ folder in the PyPO root directory.

C/C++/CUDA

A small suite of unittests for the C/C++/CUDA backend is also present and is tested using googletest. These tests are mostly testing the vector operations, but might be extended as PyPO keeps developing. If you intend to work on the backend, it might be a good thing to be able to run these tests. Please see the installation instructions for building googletest on your specific platform.

After installing googletest, the tests need to be built. Navigate to the src/ folder and run:

python3 SetupGTest.py -bmr

which should generate build scripts, make them and run the unittests in one go. For more options for the SetupGTest.py script, run:

python3 SetupGTest.py -h

Note that most backend functionality is implicitly tested through the (larger) Python unittesting suite, and if not developing in the C/C++/CUDA backend, the Python unittesting suite should be sufficient to test correct functioning of PyPO.