From 79ed488430e0992f2bd4c833270b428831848ca4 Mon Sep 17 00:00:00 2001 From: Lukas Heumos Date: Tue, 21 Jan 2025 19:19:24 +0100 Subject: [PATCH 1/3] Improve submodule documentation Signed-off-by: Lukas Heumos --- docs/contributing.md | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 0a5b318e..8118def8 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,11 +1,22 @@ # Contributing guide Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this repo, 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. +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][]. +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][]. + +## Cloning the repository + +ehrapy consists of this main repository and a git submodule [ehrapy-tutorials](https://github.com/theislab/ehrapy-tutorials) which hosts tutorial notebooks. +Clone both using: + +```bash +git clone --recurse-submodules https://github.com/theislab/ehrapy +``` + +More details on the tutorials submodule are described in ## Installing dev dependencies @@ -140,16 +151,24 @@ on how to write documentation. The documentation is set-up to render jupyter notebooks stored in the `docs/tutorials` directory using [myst-nb][]. Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells. -These notebooks come from [pert-tutorials](https://github.com/theislab/ehrapy-tutorials) which is a git submodule of ehrapy. +These notebooks come from [ehrapy-tutorials](https://github.com/theislab/ehrapy-tutorials) which is a git submodule of ehrapy. + +#### Working with the git submodule + +Whenever the tutorials are updated in the submodule, two pull requests need to be made. +Submit a pull request to [ehrapy-tutorials](https://github.com/theislab/ehrapy-tutorials) and ensure that the CI passes. +Further, submit a pull request on the ehrapy repository where the submodule also contains the commit and ensure that +the documentation as build by ReadTheDocs properly shows the updated notebooks. +Both pull requests need to be merged to ensure that no repository gets out of sync. -#### 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 From d59a72ffda44ed628fca633aa1b3bda481e68fbd Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 21 Jan 2025 18:20:45 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index 8118def8..94c90b01 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -16,7 +16,7 @@ Clone both using: git clone --recurse-submodules https://github.com/theislab/ehrapy ``` -More details on the tutorials submodule are described in +More details on the tutorials submodule are described in ## Installing dev dependencies From 033941d857f791a04399c4d1141964369316e5ca Mon Sep 17 00:00:00 2001 From: Lukas Heumos Date: Tue, 21 Jan 2025 19:21:58 +0100 Subject: [PATCH 3/3] Better ref Signed-off-by: Lukas Heumos --- docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index 8118def8..f53ea4cd 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -16,7 +16,7 @@ Clone both using: git clone --recurse-submodules https://github.com/theislab/ehrapy ``` -More details on the tutorials submodule are described in +More details on the tutorials submodule are described in the [Writing documentation](#writing-documentation) section. ## Installing dev dependencies