Contributing Guide

We welcome contributions from external contributors, and this document describes how to merge code changes into toqito.

  1. Make sure you have a GitHub account.

  2. Fork this repository on GitHub.

  3. On your local machine, clone your fork of the repository. You will have to install an editable version on your local machine. Instructions are provided below.

Warning

It would be better to avoid an editable installation via pip as poetry is a better dependency resolver.

  1. As stated in Getting started, ensure you have Python 3.10 or greater installed on your machine or in a virtual environment (pyenv, pyenv tutorial). Consider using a virtual environment. You can also use pyenv with virtualenv to manage different Python versions or conda to create virtual environments with different Python versions.

  2. Install poetry using the following command. poetry is a better dependency resolver than pip.

(local_venv) pip install poetry --upgrade pip

  1. Now, navigate to your local clone of the toqito repository as shown below.

(local_venv) cd toqito

  1. Use poetry as shown below in the toqito folder. This should install an editable version of toqito alongside other development dependencies.

(local_venv)~/toqito$ poetry install

You are now free to make the desired changes in your fork of toqito.

Making Changes

  1. Add some really awesome code to your local fork. It’s usually a good idea to make changes on a branch with the branch name relating to the feature you are going to add.

  2. When you are ready for others to examine and comment on your new feature, navigate to your fork of toqito on GitHub and open a pull request(PR) . Note that after you launch a PR from one of your fork’s branches, all subsequent commits to that branch will be added to the open pull request automatically. Each commit added to the PR will be validated for mergability, compilation and test suite compliance; the results of these tests will be visible on the PR page.

  3. If you’re adding a new feature, you must add test cases and documentation. See Adding a new feature for a detailed checklist.

  4. When the code is ready to go, make sure you run the test suite using pytest, ruff, pylint etc.

  5. When you’re ready to be considered for merging, comment on your PR that it is ready for a review to let the toqito devs know that the changes are complete. The code will not be reviewed until you have commented so, the continuous integration workflow passes, and the primary developer approves the reviews.

Testing

A convenient way to verify if the installation procedure worked correctly, use pytest in the toqito folder as shown below.

(local_venv)~/toqito$ pytest toqito/

The pytest module is used for testing and pytest-cov can be used to generate coverage reports locally. In order to run and pytest, you will need to ensure it is installed on your machine along with pytest-cov. If the editable installation process worked without any issues, both pytest and pytest-cov should be installed in your local environment.

If not, consult the pytest and pytest-cov websites for additional options on code coverage reports. For example, if your addition is not properly covered by tests, code coverage can be checked by using --cov-report term-missing options in pytest-cov.

If you are making changes to toqito.some_module, the corresponding tests should be in toqito/some_module/tests.

Code Style

We use ruff and pylint to check for formatting issues. Consult the documentation for ruff and pylint for additional information.

Do not use an autoformatter like black as the configuration settings for ruff as specified in pyproject.toml might be incompatible with the changes made by black. This is discussed in detail at this link.

References in Docstrings

If you are adding a new function, make sure the docstring of your function follows the formatting specifications in Code Style. A standard format for toqito docstring is provided below:

def my_new_function(some_parameter: parameter_type) -> return_type:
    r"""One liner description of the new function.

      Detailed description of the function.

      Examples
      ==========
      Demonstrate how the function works with expected output.

      References
      ==========
      .. bibliography::
           :filter: docname in docnames

      some_parameter: parameter_type
           Details about the input and output parameters and parameter types.
    """

Use .. math:: mode for equations and use use :cite:some_ref for some reference in the docstring.

To add an attribution to a paper or a book, add your reference with some_ref as the citation key to articles.bib or books.bib.

Following is used in a docstring for the references to show up in the documentation build.

References
==========
.. bibliography::
    :filter: docname in docnames

Documentation

We use sphinx to build the documentation and doctest to test the examples in the documentation and function docstrings. To build the documentation locally, make sure sphinx and sphinx-wagtail-theme are installed when poetry was used to install toqito.

(local_venv)~/toqito/docs$ make clean html

If you would prefer to decrease the amount of time taken by sphinx to build the documentation locally, use make html instead.

A standard document has to follow the .rst format. For more information on sphinx and sphinx-wagtail-theme, visit sphinx documentation & sphinx-wagtail-theme documentation .

To use doctest:

  • Use make doctest in toqito/docs for the docstring examples to be verified.

  • Use pytest  --doctest-glob=*.rst to check the examples in all the .rst files in toqito/docs work as expected. If you would like to only check the examples in a specific file, use pytest  --doctest-glob=tutorials.name_of_file.rst instead.

Adding a new feature

If you add a new feature to toqito, make sure

  • The function docstring follows the style guidelines as specified in References in Docstrings.

  • Added lines should show up as covered in the pytest code coverage report. See Testing.

  • Code and tests for the new feature should follow the style guidelines as discussed in Code Style.

  • Finally, if the new feature is a new module, it has to be listed in docs/autoapi_members.rst such that the new module appears in the API Reference page due to sphinx-autoapi.

Additional Resources