Update docs and readthedocs

Author: Sebastian Birk

.readthedocs.yaml

@@ -3,14 +3,18 @@ version: 2
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.10"
+    python: "3.11"
 sphinx:
   configuration: docs/conf.py
   # disable this for more lenient docs builds
-  fail_on_warning: true
+  fail_on_warning: false
 python:
   install:
+    - requirements: docs/requirements.txt
     - method: pip
       path: .
       extra_requirements:
-        - doc
+        - docsbuild
+submodules:
+    include: [docs/tutorials/notebooks]
+    recursive: true

docs/api.md

@@ -0,0 +1 @@
+# Developer

docs/api/developer.md

@@ -0,0 +1,14 @@
+# API
+
+Import MintFlow as:
+
+```
+import mintflow
+```
+
+```{toctree}
+:maxdepth: 2
+
+user
+developer
+```

docs/api/index.md

@@ -0,0 +1 @@
+# User

docs/api/user.md

@@ -1,142 +1,9 @@
-# Contributing guide
+# Contributing
 
-Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this project, too.
-This document will not reproduce the entire content from there. Instead, it aims at summarizing the most important
-information to get you started on contributing.
-
-We assume that you are already familiar with git and with making pull requests on GitHub. If not, please refer
-to the [scanpy developer guide][].
-
-## Installing dev dependencies
-
-In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build
-the documentation_. It's easy to install them using `pip`:
-
-```bash
-cd inflow
-pip install -e ".[dev,test,doc]"
-```
-
-## Code-style
-
-This package uses [pre-commit][] to enforce consistent code-styles.
-On every commit, pre-commit checks will either automatically fix issues with the code, or raise an error message.
-
-To enable pre-commit locally, simply run
-
-```bash
-pre-commit install
-```
-
-in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time.
-
-Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. If you didn't run `pre-commit` before
-pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message.
-
-If pre-commit.ci added a commit on a branch you still have been working on locally, simply use
-
-```bash
-git pull --rebase
-```
-
-to integrate the changes into yours.
-While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage.
-
-Finally, most editors have an _autoformat on save_ feature. Consider enabling this option for [ruff][ruff-editors]
-and [prettier][prettier-editors].
-
-[ruff-editors]: https://docs.astral.sh/ruff/integrations/
-[prettier-editors]: https://prettier.io/docs/en/editors.html
-
-## Writing tests
-
-```{note}
-Remember to first install the package with `pip install -e '.[dev,test]'`
-```
-
-This package uses the [pytest][] for automated testing. Please [write tests][scanpy-test-docs] for every function added
-to the package.
-
-Most IDEs integrate with pytest and provide a GUI to run tests. Alternatively, you can run all tests from the
-command line by executing
-
-```bash
-pytest
-```
-
-in the root of the repository.
-
-### Continuous integration
-
-Continuous integration will automatically run the tests on all pull requests and test
-against the minimum and maximum supported Python version.
-
-Additionally, there's a CI job that tests against pre-releases of all dependencies
-(if there are any). The purpose of this check is to detect incompatibilities
-of new package versions early on and gives you time to fix the issue or reach
-out to the developers of the dependency before the package is released to a wider audience.
-
-[scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests
-
-## Publishing a release
-
-### Updating the version number
-
-Before making a release, you need to update the version number in the `pyproject.toml` file. Please adhere to [Semantic Versioning][semver], in brief
-
-> Given a version number MAJOR.MINOR.PATCH, increment the:
->
-> 1.  MAJOR version when you make incompatible API changes,
-> 2.  MINOR version when you add functionality in a backwards compatible manner, and
-> 3.  PATCH version when you make backwards compatible bug fixes.
->
-> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
-
-Once you are done, commit and push your changes and navigate to the "Releases" page of this project on GitHub.
-Specify `vX.X.X` as a tag name and create a release. For more information, see [managing GitHub releases][]. This will automatically create a git tag and trigger a Github workflow that creates a release on PyPI.
-
-## Writing documentation
-
-Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features:
-
--   the [myst][] extension allows to write documentation in markdown/Markedly Structured Text
--   [Numpy-style docstrings][numpydoc] (through the [napoloen][numpydoc-napoleon] extension).
--   Jupyter notebooks as tutorials through [myst-nb][] (See [Tutorials with myst-nb](#tutorials-with-myst-nb-and-jupyter-notebooks))
--   [Sphinx autodoc typehints][], to automatically reference annotated input and output types
--   Citations (like {cite:p}`Virshup_2023`) can be included with [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/)
-
-See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information
-on how to write documentation.
-
-### Tutorials with myst-nb and jupyter notebooks
-
-The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [myst-nb][].
-Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells.
-It is your responsibility to update and re-run the notebook whenever necessary.
-
-If you are interested in automatically running notebooks as part of the continuous integration, please check
-out [this feature request](https://github.com/scverse/cookiecutter-scverse/issues/40) in the `cookiecutter-scverse`
-repository.
-
-#### Hints
-
--   If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. Only
-    if you do so can sphinx automatically create a link to the external documentation.
--   If building the documentation fails because of a missing link that is outside your control, you can add an entry to
-    the `nitpick_ignore` list in `docs/conf.py`
-
-#### Building the docs locally
-
-```bash
-cd docs
-make html
-open _build/html/index.html
-```
+This will be added shortly.
 
 <!-- Links -->
 
-[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html
-[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html
 [github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui
 [codecov]: https://about.codecov.io/sign-up/
 [codecov docs]: https://docs.codecov.com/docs
@@ -147,8 +14,6 @@ open _build/html/index.html
 [myst-nb]: https://myst-nb.readthedocs.io/en/latest/
 [jupytext]: https://jupytext.readthedocs.io/en/latest/
 [pre-commit]: https://pre-commit.com/
-[anndata]: https://github.com/scverse/anndata
-[mudata]: https://github.com/scverse/mudata
 [pytest]: https://docs.pytest.org/
 [semver]: https://semver.org/
 [sphinx]: https://www.sphinx-doc.org/en/master/
@@ -157,4 +22,3 @@ open _build/html/index.html
 [numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html
 [sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints
 [pypi]: https://pypi.org/
-[managing GitHub releases]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository

docs/changelog.md

@@ -1,15 +1,65 @@
-```{include} ../README.md
+# Documentation
 
-```
+MintFlow (**M**icroenvironment-induced and **IN**trinsic **T**ranscriptomic **FLOW**s) is a package for decomposing intrinsic and microenvironment-induced cellular variation in spatial transcriptomics data. MintFlow is interoperable with [AnnData](https://anndata.readthedocs.io/en/latest/) objects.
+The package is developed and maintained by the [Lotfollahi Lab](https://github.com/Lotfollahi-lab) at the Wellcome Sanger Institute.
+
+::::{grid} 1 2 3 3
+:gutter: 2
+
+:::{grid-item-card} Installation {octicon}`plug;1em;`
+:link: installation
+:link-type: doc
+
+Check out the installation guide.
+:::
+
+:::{grid-item-card} Tutorials {octicon}`play;1em;`
+:link: tutorials/index
+:link-type: doc
+
+Learn by following example applications of MintFlow.
+:::
+
+:::{grid-item-card} User Guide {octicon}`book;1em;`
+:link: user_guide/index
+:link-type: doc
+
+Review good practices for training MintFlow models on your own data.
+:::
+
+:::{grid-item-card} API {octicon}`info;1em;`
+:link: api/index
+:link-type: doc
+
+Find a detailed description of MintFlow APIs.
+:::
+
+:::{grid-item-card} Release Notes {octicon}`tag;1em;`
+:link: release_notes/index
+:link-type: doc
+
+Follow the latest changes to MintFlow.
+:::
+
+:::{grid-item-card} Contributing {octicon}`code;1em;`
+:link: contributing
+:link-type: doc
+
+Help improve Inigen.
+:::
+::::
+
+If you find Inigen useful for your research, please consider citing the Inigen manuscript.
 
 ```{toctree}
 :hidden: true
-:maxdepth: 1
+:maxdepth: 3
+:titlesonly: true
 
-api.md
-changelog.md
+installation
+tutorials/index
+api/index
+release_notes/index
 contributing.md
 references.md
-
-notebooks/example
 ```

docs/contributing.md

@@ -0,0 +1,58 @@
+# Installation
+
+MintFlow is available for Python 3.10 and 3.11.
+
+We do not recommend installation on your system Python. Please set up a virtual
+environment, e.g. via venv or conda through the [Mambaforge] distribution, or
+create a [Docker] image.
+
+To set up and activate a virtual environment with venv, run:
+
+```
+python3 -m venv ~/.venvs/mintflow
+source ~/.venvs/mintflow/bin/activate
+```
+
+To create and activate a conda environment instead, run:
+
+```
+conda create -n mintflow python=3.11
+conda activate mintflow
+```
+
+## Step 1: Installation via PyPi
+
+Install MintFlow via pip:
+```
+pip install mintflow
+```
+
+Or install including optional dependencies required for running tutorials with:
+```
+pip install mintflow[all]
+```
+
+## Step 2: Additional Libraries
+
+To use MintFlow, you need to install some additional external libraries. These include:
+- [PyTorch Scatter]
+- [PyTorch Sparse]
+
+To install these libraries, after installing MintFlow run:
+
+```
+pip install torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-${TORCH}+${CUDA}.html
+```
+where `${TORCH}` and `${CUDA}` should be replaced by the specific PyTorch and
+CUDA versions, respectively.
+
+For example, for PyTorch 2.6.0 and CUDA 12.4, type:
+```
+pip install torch_scatter torch_sparse -f https://data.pyg.org/whl/torch-2.6.0+cu124.html
+```
+
+[Mambaforge]: https://github.com/conda-forge/miniforge
+[Docker]: https://www.docker.com
+[PyTorch]: http://pytorch.org
+[PyTorch Scatter]: https://github.com/rusty1s/pytorch_scatter
+[PyTorch Sparse]: https://github.com/rusty1s/pytorch_sparse

docs/index.md

@@ -144,7 +144,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3.9.12 ('squidpy39')",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -158,7 +158,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.3"
+   "version": "3.10.12"
   },
   "vscode": {
    "interpreter": {