4. Contributing to the ect Package

Note this is a draft document and is subject to change.

4.1. Getting Started

  • Prerequisites

  • Setting up the development environment

  • Forking the ect repository

  • Cloning the repository

4.2. Contributing Guidelines

4.2.1. Code style and formatting

It is essential for this project to have well documented, clean, and readable code. The following guidelines should be followed when contributing to the ect package:

  • Use the PEP 8 style guide for Python code.

  • Follow docstring format given below for documenting functions and classes.

  • Use the Sphinx documentation system for generating documentation.

  • Always include tests for new features and bug fixes.

4.2.2. Documentation guidelines

The ect package uses the Sphinx documentation system for generating documentation. There are two things to be doing when contributing to the documentation:

  • First, include docstrings in the code which will be autogenerated into the documentation. When in doubt, write too much.

  • Second, write documentation in the doc_source directory using the reStructuredText format. This package also supports writing files in markdown, although there are some issues when dealing with autogenerated content so it’s a bit of a mix at the moment. Note that when the documentation is generated, everything in the docs folder is deleted and overwritten, so do not do your work in there, it will be lost!

Assuming everything (TODO: Add install list) is set up correctly, you can generate the documentation by running the following command from the top level folder:

make html

This will generate the documentation in the docs directory. You can view the documentation by opening the docs/index.html file in your browser.

An example of a docstring for a function is given below. Note the use of indentation since rst is picky about it:

def sort_edges(self, theta, return_g=False):
    """
    Function to sort the edges of the graph according to the function

    .. math ::

        g_\omega(e) = \max \{ g_\omega(v) \mid  v \in e \}

    in the direction of :math:`\\theta \in [0,2\pi]` .

    Parameters:
        theta (float):
            The angle in :math:`[0,2\pi]` for the direction to sort the edges.
        return_g (bool):
            Whether to return the :math:`g(v)` values along with the sorted edges.

    Returns:
        A list of edges sorted in increasing order of the :math:`g(v)` values.
        If ``return_g`` is True, also returns the ``g`` dictionary with the function values ``g[vertex_name]=func_value``.

    """

4.2.3. Testing guidelines

You should always include tests for new features and bug fixes. The ect package uses the pytest testing framework. The tests are located in the tests directory. To run the tests, you can use the following command:

pytest

or the standard unittest python framework by running:

make tests

Get in the habit of writing lots of simple tests. It is better to have too many tests than too few. The tests should be written in a way that they can be run quickly and easily. This will make it easier for you to test your code as you develop it and for others to test your code when they review it. Take a look at the existing tests for examples.

Note that in order for a function written in the test folder to be run, the function must be prefixed with test_. For example, a test function for a function called my_function would be called test_my_function.

4.2.4. Issue tracking and pull requests

If you find an issue, please post it on the GitHub issue tracker. Provide as much information as possible, including the version of the ect package you are using, the operating system you are using, and any other relevant information.

If you would like to fix an issue and you are a contributor to the project, please create a new branch for the fix. Note that the main branch is protected so you will not be able to push directly to that branch. Once you are ready to open discussion, you will create a pull request. The pull request should include a description of the issue and the fix. There is a template for pull requests that you can use to fill out helpful information.

  • Note that in order for the pip install command to work, the version number in the pyproject.toml file must be updated.

  • You should also make sure to update the version number to match in the doc_source/conf.py file. This will ensure that the documentation is updated with the correct version number.

  • Be sure to run make all before committing to ensure that the code is cleaned, the documentation is up to date, and the tests all pass.

If you are not a contributor, you will need to fork the code and create a pull request from your fork. Note that all pull requests need to be approved by Liz Munch before they can be merged.

4.3. Conclusion

  • Acknowledgements

  • Future development plans

  • Contact information and support