Contributing Guide

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

Make sure you have a GitHub account.
Fork this repository on GitHub.
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 due to a slew of known issues.

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.
Install poetry using the following command. poetry is a better dependency resolver than pip.

(local_venv) pip install poetry --upgrade pip

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

(local_venv) cd toqito

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

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.
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.
If you’re adding a new feature, you must add test cases and documentation. See Adding a new feature for a detailed checklist.
When the code is ready to go, make sure you run the test suite using pytest.
When you’re ready to be considered for merging, check the “Ready to go” box on the PR page to let the toqito devs know that the changes are complete. The code will not be merged until this box is checked, the continuous integration returns check marks, 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. To build the documentation locally, make sure sphinx and sphinx-rtd-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-rtd-theme, visit sphinx documentation & sphinx-rtd-theme documentation .

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 alphabetically as autoapi/new_module/index in autoapi_members.rst available in the docs folder. When Sphinx is run locally, the new module should then appear to be listed in the API Reference page.