Adding contributing guide and manuscript link (#593)

* contributing guide and link on homepage

* fixing links

* fix links

* fix links for sure

* correct tox commands

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* removed troubleshooting

* m not M in moscot

---------

Co-authored-by: Arina Danilina <[email protected]>
Co-authored-by: Giovanni Palla <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

docs/contributing.rst

@@ -1,3 +1,154 @@
-Contributing
-============
-Under construction. Please feel free to reach out!
+Contributing guide
+~~~~~~~~~~~~~~~~~~
+
+Table of Contents
+=================
+- `Contributing to moscot`_
+- `Codebase structure`_
+- `Code style guide`_
+- `Testing`_
+- `Writing documentation`_
+- `Writing tutorials/examples`_
+- `Making a new release`_
+- `Creating release notes`_
+- `Submitting a PR`_
+
+Contributing to moscot
+-----------------------
+Clone moscot from source as::
+
+    git clone https://github.com/theislab/moscot
+    cd moscot
+    git checkout main
+
+Install the test and development mode::
+
+    pip install -e'.[dev,test]'
+
+Optionally install pre-commit. This will ensure that the pushed code passes the linting steps::
+
+    pre-commit install
+
+Although the last step is not necessary, it is highly recommended, since it will help you to pass the linting step
+(see `Code style guide`_). If you did install ``pre-commit`` but are unable to decipher some flags, you can
+still commit using the ``--no-verify``.
+
+Codebase structure
+------------------
+The moscot project:
+
+- `moscot <../src/moscot>`_: the root of the package.
+
+  - `moscot/backends <../src/moscot/backends>`_: the OTT backend module, which deals with OTT solvers and output functions.
+  - `moscot/base <../src/moscot/base>`_: contains base moscot classes.
+    - `moscot/base/problems <../src/moscot/base/problems>`_: the moscot problems module.
+  - `moscot/costs <../src/moscot/costs>`_: contains different costs computation functions.
+  - `moscot/plotting <../src/moscot/plotting>`_: the plotting module.
+  - `moscot/problems <../src/moscot/problems>`_: the functionality of general problems classes, subdivided into problem types.
+  - `moscot/utils <../src/moscot/utils>`_: contains various utility functions.
+  - `moscot/datasets.py <../src/moscot/datasets.py>`_: contains loading and simulating functions for the datasets.
+
+Tests structure:
+
+- `tests <../tests>`_: the root of the package
+
+  - `tests/backends <../tests/backends>`_: tests for the ott backend.
+  - `tests/costs <../tests/costs>`_ tests for the solving costs.
+  - `tests/data <../tests/data>`_: tests for the simulated data module.
+  - `tests/datasets <../tests/datasets>`_: tests for the datasets.
+  - `tests/plotting <../tests/plotting>`_ tests for the plotting module.
+  - `tests/problems <../tests/problems>`_ tests for the problem classes, divided by problem type.
+  - `tests/solvers <../tests/solvers>`_ tests for the solvers.
+  - `tests/utils <../tests/utils>`_ tests for the utility functions.
+  - `tests/conftest.py <../tests/conftest.py>`_: ``pytest`` fixtures and utility functions.
+
+Code style guide
+----------------
+We rely on ``black`` and ``isort`` to do the most of the formatting - both of them are integrated as pre-commit hooks.
+You can use ``tox`` to check the changes::
+
+    tox -e lint-code
+
+Furthermore, we also require that:
+
+- functions are fully type-annotated.
+- exception messages are capitalized and end with ``.``.
+- warning messages are capitalized and do not end with ``.``.
+- when referring to variable inside an error/warning message, enclose its name in \`.
+- when referring to variable inside a docstrings, enclose its name in \``.
+
+Testing
+-------
+We use ``tox`` to automate our testing, as well as linting and documentation creation. To run the tests, run::
+
+    tox -e py{38,39,310,311}-{linux,macos}
+
+depending on the Python version(s) in your ``PATH`` and your operating system. We use ``flake8`` and ``mypy`` to further
+analyze the code. Use ``# noqa: <error1>,<error2>`` to ignore certain ``flake8`` errors and
+``# type: ignore[error1,error2]`` to ignore specific ``mypy`` errors.
+
+To run only a subset of tests, run::
+
+    tox -e <environment> -- <name>
+
+where ``<name>`` can be a path to a test file/directory or a name of a test function/class.
+For example, to run only the tests in the ``plotting`` module, use::
+
+    tox -e py39-linux -- tests/plotting/test_plotting.py
+
+If needed, a specific ``tox`` environment can be recreated as::
+
+    tox -e <environment> --recreate
+
+Writing documentation
+---------------------
+We use ``numpy``-style docstrings for the documentation with the following additions and modifications:
+
+- no type hints in the docstring (applies also for the return statement) are allowed,
+  since all functions are required to have the type hints in their signatures.
+- when referring to some argument within the same docstring, enclose that reference in \`\`.
+- prefer putting references in the ``references.bib`` instead under the ``References`` sections of the docstring.
+- use ``docrep`` for repeating documentation.
+
+In order to build the documentation, run::
+
+    tox -e build-docs
+
+Since the tutorials are hosted on a separate repository (see `Writing tutorials/examples`_), we download the newest
+tutorials/examples from there and build the documentation here.
+
+To validate the links inside the documentation, run::
+
+    tox -e lint-docs
+
+If you need to clean the artifacts from previous documentation builds, run::
+
+    tox -e clean-docs
+
+Writing tutorials/examples
+--------------------------
+Tutorials and examples are hosted on a separate repository called `moscot_notebooks
+<https://github.com/theislab/moscot_notebooks>`_.
+Please refer to this `guide <https://github.com/theislab/moscot_notebooks/blob/main/CONTRIBUTING.rst>`_ for more information.
+
+Submitting a PR
+---------------
+Before submitting a new pull request, please make sure you followed these instructions:
+
+- make sure that you've branched off ``main`` and are merging into ``main``
+- make sure that your code follows the above specified conventions
+  (see `Code style guide`_ and `Writing documentation`_).
+- if applicable, make sure you've added/modified at least 1 test to account for the changes you've made
+- make sure that all tests pass locally (see `Testing`_).
+- if there is no issue which this PR solves, create a new `one <https://github.com/theislab/moscot/issues/new>`_
+  briefly explaining what the problem is.
+- make sure that the section under ``## Description`` is properly formatted if automatically generating release notes,
+  see also `Creating release notes`_.
+
+Making a new release
+--------------------
+TODO
+
+Creating release notes
+----------------------
+TODO

docs/index.rst

@@ -16,7 +16,7 @@ Moscot - Multiomics Single-cell Optimal Transport
     :align: center
     :class: only-dark
 
-If you find a model useful for your research, please consider citing the ``moscot`` manuscript (in preparation) as
+If you find a model useful for your research, please consider citing the ``moscot`` manuscript [`Klein et al., 2023 <https://www.biorxiv.org/content/10.1101/2023.05.11.540374v2>`_] as
 well as the publication introducing the model, which can be found in the corresponding documentation.
 
 .. grid:: 3