Update docs website (icbi-lab#22)

* website structure * update API doc * rename notebooks * fix references * add warning to README * fix typos
vjmarteau · Apr 14, 2023 · f196512 · f196512
1 parent 38b46b2
commit f196512
Show file tree

Hide file tree

Showing 22 changed files with 1,013 additions and 898 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# atlas_protocol
+# Protocol for atlas-level integration and analysis of single cells
 
 [![Tests][badge-tests]][link-tests]
 [![Documentation][badge-docs]][link-docs]
@@ -7,30 +7,27 @@
 [link-tests]: https://github.com/icbi-lab/atlas_protocol/actions/workflows/test.yml
 [badge-docs]: https://img.shields.io/readthedocs/atlas_protocol
 
-A computational protocol for atlas-level data integration and analysis as performed in Salcher et al. (2022).
+A computational protocol for atlas-level data integration, downstream analysis and linking with phenotypic information
+from bulk RNA-seq data as performed in [Salcher et al. (2022)](<https://www.cell.com/cancer-cell/fulltext/S1535-6108(22)00499-8>).
 
-## Getting started
-
-Please refer to the [documentation][link-docs]. In particular, the
+> **Warning**: This repository is currently under active development. This means, some parts are still incomplete
+> and there are probably still a lot of mistakes.
 
--   [API documentation][link-api].
+## Getting started
 
-## Installation
+This repository consists of two parts:
 
-You need to have Python 3.8 or newer installed on your system. If you don't have
-Python installed, we recommend installing [Mambaforge](https://github.com/conda-forge/miniforge#mambaforge).
+-   An [online version][link-docs] of the protocol
+-   A python package (`atlas_protocol_scripts`) providing utility functions used in the protocol.
 
-There are several alternative options to install atlas_protocol:
+For **prerequisites** and instructions to **obtain data** and **software dependencies** for running
+the tutorial, please see the ["before you begin"][before-you-begin] section in the documentation.
 
-<!--
-1) Install the latest release of `atlas_protocol` from `PyPI <https://pypi.org/project/atlas_protocol/>`_:
+For **details on the helper functions**, see the [API documentation][link-api].
 
-```bash
-pip install atlas_protocol
-```
--->
+## Installation
 
-1. Install the latest development version:
+The package with helper functions can be installed from GitHub as follows:
 
 ```bash
 pip install git+https://github.com/icbi-lab/atlas_protocol.git@main
@@ -42,8 +39,7 @@ See the [changelog][changelog].
 
 ## Contact
 
-For questions and help requests, you can reach out in the [scverse discourse][scverse-discourse].
-If you found a bug, please use the [issue tracker][issue-tracker].
+Please use the [issue tracker][issue-tracker].
 
 ## Citation
 
@@ -54,3 +50,4 @@ If you found a bug, please use the [issue tracker][issue-tracker].
 [changelog]: https://atlas_protocol.readthedocs.io/latest/changelog.html
 [link-docs]: https://atlas_protocol.readthedocs.io
 [link-api]: https://atlas_protocol.readthedocs.io/latest/api.html
+[before-you-begin]: https://atlas-protocol.readthedocs.io/en/latest/before-you-begin.html
diff --git a/docs/api.md b/docs/api.md
@@ -1,19 +1,40 @@
 # API
 
-## Plotting
+## Preprocessing
 
 ```{eval-rst}
-.. module:: atlas_protocol_scripts.pl
+.. module:: atlas_protocol_scripts.pp
 .. currentmodule:: atlas_protocol_scripts
 
 .. autosummary::
     :toctree: generated
 
     pp.is_outlier
+```
+
+## Tools
+
+```{eval-rst}
+.. module:: atlas_protocol_scripts.tl
+.. currentmodule:: atlas_protocol_scripts
+
+.. autosummary::
+    :toctree: generated
 
     tl.fdr_correction
     tl.scissor_wilcoxon_test
     tl.CpdbAnalysis
 
+```
+
+## Plotting
+
+```{eval-rst}
+.. module:: atlas_protocol_scripts.pl
+.. currentmodule:: atlas_protocol_scripts
+
+.. autosummary::
+    :toctree: generated
+
     pl.significance_heatmap
 ```
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,6 +28,7 @@
 
 bibtex_bibfiles = ["references.bib"]
 bibtex_reference_style = "author_year"
+bibtex_default_style = "plain"
 templates_path = ["_templates"]
 nitpicky = True  # Warn about broken links
 needs_sphinx = "4.0"

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -20,8 +20,7 @@ pip install -e ".[dev,test,doc]"
 ## Code-style
 
 This template 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. See [pre-commit checks](template_usage.md#pre-commit-checks) for
-a full list of checks enabled for this repository.
+automatically fix issues with the code, or raise an error message.
 
 To enable pre-commit locally, simply run
 
@@ -73,24 +72,12 @@ in the root of the repository. Continuous integration will automatically run the
 
 ### Updating the version number
 
-Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief
+Before making a release, you need to update the version number. Please adhere to [Calender Versioning][calver].
 
-> 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.
+In brief,
 
-We use [bump2version][] to automatically update the version number in all places and automatically create a git tag.
-Run one of the following commands in the root of the repository
-
-```bash
-bump2version patch
-bump2version minor
-bump2version major
-```
+-   update the version number in `pyproject.toml`
+-   create a git tag, e.g. `git tag v2023.04.01`
 
 Once you are done, run
 
@@ -100,40 +87,6 @@ git push --tags
 
 to publish the created tag on GitHub.
 
-[bump2version]: https://github.com/c4urself/bump2version
-
-### Building and publishing the package on PyPI
-
-Python packages are not distributed as source code, but as _distributions_. The most common distribution format is the so-called _wheel_. To build a _wheel_, run
-
-```bash
-python -m build
-```
-
-This command creates a _source archive_ and a _wheel_, which are required for publishing your package to [PyPI][]. These files are created directly in the root of the repository.
-
-Before uploading them to [PyPI][] you can check that your _distribution_ is valid by running:
-
-```bash
-twine check dist/*
-```
-
-and finally publishing it with:
-
-```bash
-twine upload dist/*
-```
-
-Provide your username and password when requested and then go check out your package on [PyPI][]!
-
-For more information, follow the [Python packaging tutorial][].
-
-It is possible to automate this with GitHub actions, see also [this feature request][pypi-feature-request]
-in the cookiecutter-scverse template.
-
-[python packaging tutorial]: https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives
-[pypi-feature-request]: https://github.com/scverse/cookiecutter-scverse/issues/88
-
 ## Writing documentation
 
 Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features:
@@ -152,18 +105,14 @@ The documentation is set-up to render jupyter notebooks stored in the `docs/note
 Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells.
 It is your reponsibility 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
+### 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
+### Building the docs locally
 
 ```bash
 cd docs
@@ -195,3 +144,4 @@ 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/
+[calver]: https://calver.org/
diff --git a/docs/index.md b/docs/index.md
@@ -4,26 +4,49 @@
 
 ```{toctree}
 :hidden: true
-:maxdepth: 1
+:maxdepth: 2
 
 before-you-begin.md
+```
 
-notebooks/03_merge.ipynb
-notebooks/02_seed_annotation.ipynb
-notebooks/03-2_qc.ipynb
+```{toctree}
+:hidden: true
+:caption: Building a single-cell atlas
+:maxdepth: 2
+
+notebooks/01_merge.ipynb
+notebooks/02_qc.ipynb
+notebooks/03_seed_annotation.ipynb
 notebooks/04_integrate_scvi.ipynb
 notebooks/05_cell_type_annotation.ipynb
+```
+
+```{toctree}
+:hidden: true
+:caption: Downstream analysis
+:maxdepth: 2
 
 notebooks/09_compositional.ipynb
 notebooks/15_cell_cell_communication.ipynb
 notebooks/10_bulk_integration.ipynb
 
 the-next-steps.md
+```
+
+```{toctree}
+:hidden: true
+:caption: Helper package documentation
+:maxdepth: 2
 
 api.md
+```
+
+```{toctree}
+:hidden: true
+:caption: About this project
+:maxdepth: 2
+
 changelog.md
-template_usage.md
 contributing.md
 references.md
-
 ```
diff --git a/docs/notebooks/03_merge.ipynb → docs/notebooks/01_merge.ipynb b/docs/notebooks/03_merge.ipynb → docs/notebooks/01_merge.ipynb
diff --git a/docs/notebooks/03_merge.py → docs/notebooks/01_merge.py b/docs/notebooks/03_merge.py → docs/notebooks/01_merge.py
diff --git a/docs/notebooks/03-2_qc.ipynb → docs/notebooks/02_qc.ipynb b/docs/notebooks/03-2_qc.ipynb → docs/notebooks/02_qc.ipynb
diff --git a/docs/notebooks/03-2_qc.py → docs/notebooks/02_qc.py b/docs/notebooks/03-2_qc.py → docs/notebooks/02_qc.py
diff --git a/docs/notebooks/02_seed_annotation.ipynb b/docs/notebooks/02_seed_annotation.ipynb
diff --git a/docs/notebooks/02_seed_annotation.py b/docs/notebooks/02_seed_annotation.py