Merge pull request #18 from quadbio/feature/improve_docs

Update the Readme

CHANGELOG.md

@@ -12,4 +12,4 @@ and this project adheres to [Semantic Versioning][].
 
 ### Added
 
--   Basic tool, preprocessing and plotting functions
+- Basic tool, preprocessing and plotting functions

README.md

@@ -3,19 +3,22 @@
 [![Tests][badge-tests]][tests]
 [![Coverage][badge-coverage]][coverage]
 [![Documentation][badge-docs]][documentation]
+[![Pre-commit.ci][badge-pre-commit]][pre-commit]
 
 [badge-tests]: https://img.shields.io/github/actions/workflow/status/quadbio/cell-annotator/test.yaml?branch=main
 [badge-coverage]: https://codecov.io/gh/quadbio/cell-annotator/branch/main/graph/badge.svg
 [badge-docs]: https://img.shields.io/readthedocs/cell-annotator
+[badge-pre-commit]: https://results.pre-commit.ci/badge/github/quadbio/cell-annotator/main.svg
 
-A tool to annotate cell types based on marker genes using OpenAI models. Inspired by [Hou et al., Nature Methods 2024](https://www.nature.com/articles/s41592-024-02235-4) and [https://github.com/VPetukhov/GPTCellAnnotator](https://github.com/VPetukhov/GPTCellAnnotator).
+A tool to annotate cell types based on marker genes using OpenAI models.
 
 ## Key features
 
--   Automatically annotate cells including type, state and confidence fields.
--   Generate consistent annotations across samples of your study.
--   Optionally infuse prior knowledge by providing information about your biological system.
--   Retrieve reliable results thanks to [OpenAI structured outputs](https://platform.openai.com/docs/guides/structured-outputs)
+- Automatically annotate cells including type, state and confidence fields.
+- Generate consistent annotations across samples of your study.
+- Optionally infuse prior knowledge by providing information about your biological system.
+- Retrieve reliable results thanks to [OpenAI structured outputs](https://platform.openai.com/docs/guides/structured-outputs)
+- Use pre-integration cell type labels to either score your integration quality (e.g. [scIB metrics](https://scib-metrics.readthedocs.io/en/stable/)) or to guide your integration effort (e.g. [scPoli](https://docs.scarches.org/en/latest/), [scANVI](https://docs.scvi-tools.org/en/stable/api/reference/scvi.model.SCANVI.html))
 
 ## Installation
 
@@ -30,10 +33,14 @@ pip install git+https://github.com/quadbio/cell-annotator.git@main
 
 ## Getting started
 
-After installation, head over to OpenAI to generate your API key: https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key
+After installation, head over to OpenAI to generate your [API key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key)
 
 Keep this key private and don't share it with anyone. `CellAnnotator` will try to read the key as an environmental variable - either expose it to the environment yourself, or store it as an `.env` file anywhere within the repository where you conduct your analysis and plan to run `CellAnnotator`. The package will then use [dotenv](https://pypi.org/project/python-dotenv/) to export the key from the `env` file as an environmental variable.
 
+## Credits
+
+This tool was inspired by [Hou et al., Nature Methods 2024](https://www.nature.com/articles/s41592-024-02235-4) and [https://github.com/VPetukhov/GPTCellAnnotator](https://github.com/VPetukhov/GPTCellAnnotator).
+
 ## Contact
 
 If you found a bug, please use the [issue tracker][].
@@ -43,3 +50,4 @@ If you found a bug, please use the [issue tracker][].
 [tests]: https://github.com/quadbio/cell-annotator/actions/workflows/test.yaml
 [coverage]: https://codecov.io/gh/quadbio/cell-annotator
 [documentation]: https://cell-annotator.readthedocs.io
+[pre-commit]: https://results.pre-commit.ci/latest/github/quadbio/cell-annotator/main

docs/contributing.md

@@ -155,11 +155,11 @@ This will automatically create a git tag and trigger a Github workflow that crea
 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}`virshup2023scverse`) can be included with [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/)
+- 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}`virshup2023scverse`) can be included with [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/)
 
 See scanpy’s {doc}`scanpy:dev/documentation` for more information on how to write your own.
 
@@ -183,10 +183,10 @@ please check out [this feature request][issue-render-notebooks] in the `cookiecu
 
 #### 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`
+- 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`
 
 (docs-building)=