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
withvirtualenv
to manage different Python versions.Install
poetry
using the following command.poetry
is a better dependency resolver thanpip
.
(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 thetoqito
folder. This should install an editable version oftoqito
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
inautoapi_members.rst
available in thedocs
folder. When Sphinx is run locally, the new module should then appear to be listed in theAPI Reference
page.