From d6ec9ce55b85ebdabb6faf6b4c1f8fd534f1440f Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 20:51:57 -0500 Subject: [PATCH 01/17] delete req.txt --- requirements.txt | 20 -------------------- 1 file changed, 20 deletions(-) delete mode 100644 requirements.txt diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 515edfd9f..000000000 --- a/requirements.txt +++ /dev/null @@ -1,20 +0,0 @@ -sphinx<8 # break build docs because of warnings -sphinx-autobuild -sphinx-tabs -sphinx-tags -sphinx-design -sphinx-external-toc -sphinx-favicon>=1.0 -sphinx-copybutton -sphinx-gallery -sphinx_autodoc_typehints==1.12.0 -sphinxcontrib-mermaid>=1.0.0 -myst-nb -napari-sphinx-theme>=0.3.0 -matplotlib -lxml_html_clean -imageio-ffmpeg -pydeps -seedir -pytest -linkify-it-py From 0fca518046f878bec8b6797c6478badf02cded64 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 20:52:33 -0500 Subject: [PATCH 02/17] remove docs-install (it's all handled by napari install now) --- Makefile | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Makefile b/Makefile index dba1164f0..9244c5b0d 100644 --- a/Makefile +++ b/Makefile @@ -20,10 +20,6 @@ clean: rm -rf $(docs_dir)/gallery/* rm -rf $(docs_dir)/_tags -docs-install: - python -m pip install -qr $(current_dir)requirements.txt - python -m pip freeze - prep-docs: python $(docs_dir)/_scripts/prep_docs.py From a4a6ff12f426f27665a1dd604e96c2e9ac732cf4 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 20:53:06 -0500 Subject: [PATCH 03/17] remove make docs in favor of make html --- Makefile | 2 -- 1 file changed, 2 deletions(-) diff --git a/Makefile b/Makefile index 9244c5b0d..95ac01c6f 100644 --- a/Makefile +++ b/Makefile @@ -29,8 +29,6 @@ docs-build: prep-docs docs-xvfb: prep-docs NAPARI_CONFIG="" NAPARI_APPLICATION_IPY_INTERACTIVE=0 xvfb-run --auto-servernum sphinx-build -M html docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS) -docs: clean docs-install docs-build - html: clean docs-build # Implies noplot, but no clean - call 'make clean' manually if needed From 7aef6525d3a73b7f746f7d4983e422f81bd2fe68 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 20:58:12 -0500 Subject: [PATCH 04/17] Update docs contributing guide to state where docs dependnecies are --- docs/developers/contributing/documentation/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 0bea0d6d3..5e72036cf 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -28,6 +28,7 @@ This is documentation is written with [Jinja](https://jinja.palletsprojects.com/ 5. The [API reference documentation](api) is autogenerated from the napari source code docstrings. Docstrings are written in the [reStructuredText format](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) and any modifications to them should be submitted to the [napari/napari](https://github.com/napari/napari) repository. +6. Importantly, all of the dependencies for building the documentation are in the [the pyproject.toml of napari/napari](https://github.com/napari/napari/blob/main/pyproject.toml) under the optional dependencies `docs` and `gallery`. (contributing-without-local-setup)= ## Contributing to the napari documentation without a local setup From 19d767fdedce7783a0794da9ae76a5b21cd9642d Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 21:11:43 -0500 Subject: [PATCH 05/17] Install napari with docs dependencies --- .../developers/contributing/documentation/index.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 5e72036cf..158096f8e 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -89,9 +89,17 @@ cd napari-docs/ Since the API reference documentation (autogenerated from the napari code docstrings) and the example gallery are sourced from the `napari/napari` repository, before you can build the documentation locally, you need: -- a clean `conda` environment; -- a development installation of napari in that environment. Follow the [contributor guide](dev-installation) for details on how to do this; -- the napari documentation requirements. Starting at the folder where you cloned the `napari/docs` repository, and after activating your clean `conda` environment, you can install these with `python -m pip install -r requirements.txt`. +- a clean `conda` environment—remember to activate it!; +- a from-source, editable installation of napari with the optional `docs` dependencies and a Qt backend. Change directories to where you cloned napari and run, for example: + + ```bash + python -m pip install -e ".[pyqt, docs]" + ``` + This will use the default Qt backend. For other options, see [the napari installation guide](https://napari.org/stable/tutorials/fundamentals/installation.html#choosing-a-different-qt-backend). + + ````{note} + You can combine the documentation dependencies with [a development installation of napari](dev-installation) by adding `docs` to the dependencies in `[]`, e.g. `[pyqt, dev, docs]`. + ```` This setup, with these dependencies, will allow you to preview your document locally as it would appear on `napari.org`. It will also install [Jupyter notebook](https://jupyter.org/) and [jupytext](https://jupytext.readthedocs.io), which you will need to contribute documents containing code or viewer interactions. From c1b2b1eaf8f1abf4380336b5f5863f0bf612783f Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 21:12:08 -0500 Subject: [PATCH 06/17] Remove out-dated jupyter/jupytext --- docs/developers/contributing/documentation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 158096f8e..8dc3d1c0d 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -101,7 +101,7 @@ Since the API reference documentation (autogenerated from the napari code docstr You can combine the documentation dependencies with [a development installation of napari](dev-installation) by adding `docs` to the dependencies in `[]`, e.g. `[pyqt, dev, docs]`. ```` -This setup, with these dependencies, will allow you to preview your document locally as it would appear on `napari.org`. It will also install [Jupyter notebook](https://jupyter.org/) and [jupytext](https://jupytext.readthedocs.io), which you will need to contribute documents containing code or viewer interactions. +This setup, with these dependencies, will allow you to preview your document locally as it would appear on `napari.org`. ## 0. Before you start From e44cfd591a187a632cccdb04a113f2361d7e0d83 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 21:18:49 -0500 Subject: [PATCH 07/17] update build instructions to use make html --- .../contributing/documentation/index.md | 22 ++++++++----------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 8dc3d1c0d..8835d3fd6 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -174,10 +174,7 @@ Jupyter notebook, or in your preferred text editor. ```{admonition} Already have a notebook? :class: tip -If you have an existing `.ipynb` Jupyter notebook that you'd like to contribute, you can convert it to MyST markdown -and then edit the `.md` file to prepare it for contributing. - -Run `jupytext your-notebook.ipynb --to myst` to create a new MyST version of your file, +If you have an existing `.ipynb` Jupyter notebook that you'd like to contribute, you can convert it to MyST markdown and then edit the `.md` file to prepare it for contributing. For the conversion, you can use the [`jupytext` package](https://jupytext.readthedocs.io/en/latest/). Run `jupytext your-notebook.ipynb --to myst` to create a new MyST version of your file, `your-notebook.md`. Edit this file to include the relevant sections from the docs template. ``` @@ -289,12 +286,12 @@ To see the markdown document structure and content change in real-time without b ### 3.1. Building locally -To build the documentation locally from scratch, run `make docs` from the root +To build the documentation locally from scratch, run `make html` from the root of your local clone of the `napari/docs` repository (assuming you've installed -the [docs prerequisites](prerequisites)). +napari with the [docs prerequisites](prerequisites)). ```bash -make docs +make html ``` If the changes you have made to documentation don't involve changing the napari gallery, @@ -302,7 +299,6 @@ you can speed up this build by running `make html-noplot` instead. This will ski gallery build, which involves launching up napari and rendering all the examples. ```bash -make docs-install # only needed the first time make html-noplot ``` @@ -316,13 +312,13 @@ $ python3 -m http.server --directory docs/_build/html ``` ````{note} -The `make docs` command above assumes you have a local clone of the +The `make html` command above assumes you have a local clone of the [`napari/napari`](https://github.com/napari/napari) repo at the same level as the `napari/docs` clone. If that's not the case, you can specify the location of the examples gallery folder by executing ```bash -make docs GALLERY_PATH= +make html GALLERY_PATH= ``` The `GALLERY_PATH` option must be given relative to the `docs` folder. If your @@ -342,7 +338,7 @@ folder structure is Then the command would be ```bash -make docs GALLERY_PATH=../../napari/examples +make html GALLERY_PATH=../../napari/examples ``` ```` @@ -476,7 +472,7 @@ Then install Git Bash and build the documentation: 2. Activate your virtual environment in Git Bash. - Conda environment: To have your conda environment available in Git Bash, launch Git Bash, then run `conda init bash` from anaconda prompt and restart Git Bash. The conda environment can then be activated from Git Bash with `conda activate `. - Virtualenv: To have your virtualenv available in Git Bash, launch Git Bash, then run `source /Scripts/activate`. -3. From Git Bash, `cd` to the napari docs repository and run `make docs` or other `make` commands to build the documentation. +3. From Git Bash, `cd` to the napari docs repository and run `make html` or other `make` commands to build the documentation. ```{tip} If you use Git Bash a lot, you may want to set conda to not initialize on bash by default to speed up the launch process. This can be done with `conda config --set auto_activate_base false`. You can then activate conda in Git Bash with `conda activate base`. @@ -506,7 +502,7 @@ We will use Ubuntu for this guide since it is the default WSL distribution, easy 8. `pip install pyqt5-tools`. 9. Fork the napari docs repository and clone it to the same parent folder as the napari repository (see [](prerequisites)). Then navigate to the napari docs folder via `cd napari-docs`. 10. Install `make` with `sudo apt install make`. -11. Run `make docs` or other `make` commands to build the documentation. +11. Run `make html` or other `make` commands to build the documentation. ````{admonition} Route graphical output to Windows :class: tip From 09d9b899fe3f0b5b7735c1a296e9d7aca0db181f Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 21:21:58 -0500 Subject: [PATCH 08/17] update README --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 77267bab0..19332f659 100644 --- a/README.md +++ b/README.md @@ -17,14 +17,13 @@ Please read our [contributing guide](https://napari.org/dev/developers/contribut ### quickstart: local setup * __Check the prerequisites__ 1. Create a clean Python environment (e.g., with conda). - 1. In that environment, create a [development installation](https://napari.org/dev/developers/contributing/dev_install.html#dev-installation) of `napari` on your local machine, first forking and cloning the main `napari` project if you've not previously done so. - 1. Fork this repository, and then clone your fork to your local machine. NB: you may want to name your fork e.g. `napari-docs` rather than just `docs`. - 1. With your local clone's root folder as the working directory, and with the environment created in the first step activated, install the docs requirements with `python -m pip install -r requirements.txt`. + 1. In that environment, create an editable `napari` installation with the `docs` dependency group and a Qt backend. For example, after first forking and cloning the main `napari` project if you've not previously done so, run `python -m pip install -e ".pyqt, docs]"` from your `napari/napari` clone directory. This will use the default Qt backend. + 1. Fork *this* repository, `napari/docs`, and then clone your fork to your local machine. NB: you may want to name your fork e.g. `napari-docs` rather than just `docs`. * __Build__ locally * If you're building on Windows, a few extra steps are required; you can follow [this guide](https://napari.org/dev/developers/contributing/documentation/index.html#building-the-documentation-on-windows). * From the root of your local clone of this repository, run one of these: - * `make docs`, if your changes include the example gallery - * `make docs-install && make html-noplot`, otherwise + * `make html`, if your changes include the example gallery + * `make html-noplot`, otherwise * __Preview__ locally, either dragging-and-dropping `docs/_build/index.html` into a browser, or deploying a local server with `python3 -m http.server --directory docs/_build`. These steps should set you up to build and preview your docs contributions on your local machine. From 1c4ab61eef71b87c0e51ba1f6302ad0a1ba94671 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 21:54:39 -0500 Subject: [PATCH 09/17] missing bracket --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 19332f659..1b7d718e6 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Please read our [contributing guide](https://napari.org/dev/developers/contribut ### quickstart: local setup * __Check the prerequisites__ 1. Create a clean Python environment (e.g., with conda). - 1. In that environment, create an editable `napari` installation with the `docs` dependency group and a Qt backend. For example, after first forking and cloning the main `napari` project if you've not previously done so, run `python -m pip install -e ".pyqt, docs]"` from your `napari/napari` clone directory. This will use the default Qt backend. + 1. In that environment, create an editable `napari` installation with the `docs` dependency group and a Qt backend. For example, after first forking and cloning the main `napari` project if you've not previously done so, run `python -m pip install -e "[.pyqt, docs]"` from your `napari/napari` clone directory. This will use the default Qt backend. 1. Fork *this* repository, `napari/docs`, and then clone your fork to your local machine. NB: you may want to name your fork e.g. `napari-docs` rather than just `docs`. * __Build__ locally * If you're building on Windows, a few extra steps are required; you can follow [this guide](https://napari.org/dev/developers/contributing/documentation/index.html#building-the-documentation-on-windows). From 23ec4bb86437e120f4f4ba41e3f3eec7d10964e9 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Thu, 27 Feb 2025 21:56:21 -0500 Subject: [PATCH 10/17] clarify dev and docs --- docs/developers/contributing/documentation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 8835d3fd6..00f8b2af5 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -98,7 +98,7 @@ Since the API reference documentation (autogenerated from the napari code docstr This will use the default Qt backend. For other options, see [the napari installation guide](https://napari.org/stable/tutorials/fundamentals/installation.html#choosing-a-different-qt-backend). ````{note} - You can combine the documentation dependencies with [a development installation of napari](dev-installation) by adding `docs` to the dependencies in `[]`, e.g. `[pyqt, dev, docs]`. + You can combine the documentation dependencies with [a development installation of napari](dev-installation) by having both `dev` and `docs` in the dependencies, e.g. `[pyqt, dev, docs]`. ```` This setup, with these dependencies, will allow you to preview your document locally as it would appear on `napari.org`. From 909cd9030ce2e693ad4633f311f3c3e7924d0866 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Tue, 4 Mar 2025 08:10:59 -0500 Subject: [PATCH 11/17] Update docs/developers/contributing/documentation/index.md Co-authored-by: Carol Willing --- docs/developers/contributing/documentation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 00f8b2af5..653d2af89 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -28,7 +28,7 @@ This is documentation is written with [Jinja](https://jinja.palletsprojects.com/ 5. The [API reference documentation](api) is autogenerated from the napari source code docstrings. Docstrings are written in the [reStructuredText format](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) and any modifications to them should be submitted to the [napari/napari](https://github.com/napari/napari) repository. -6. Importantly, all of the dependencies for building the documentation are in the [the pyproject.toml of napari/napari](https://github.com/napari/napari/blob/main/pyproject.toml) under the optional dependencies `docs` and `gallery`. +6. Importantly, all of the dependencies for building the documentation are in the [the `pyproject.toml` of napari/napari](https://github.com/napari/napari/blob/main/pyproject.toml) under the optional dependencies `docs` and `gallery`. (contributing-without-local-setup)= ## Contributing to the napari documentation without a local setup From 83df3cff96d61fb119a38f8a1c44dc01789d0ad3 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Sat, 8 Mar 2025 11:40:07 -0500 Subject: [PATCH 12/17] clarify that jupytext needs to be installed --- docs/developers/contributing/documentation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 653d2af89..8a1214229 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -174,7 +174,7 @@ Jupyter notebook, or in your preferred text editor. ```{admonition} Already have a notebook? :class: tip -If you have an existing `.ipynb` Jupyter notebook that you'd like to contribute, you can convert it to MyST markdown and then edit the `.md` file to prepare it for contributing. For the conversion, you can use the [`jupytext` package](https://jupytext.readthedocs.io/en/latest/). Run `jupytext your-notebook.ipynb --to myst` to create a new MyST version of your file, +If you have an existing `.ipynb` Jupyter notebook that you'd like to contribute, you can convert it to MyST markdown and then edit the `.md` file to prepare it for contributing. For the conversion, you can install the [`jupytext` package](https://jupytext.readthedocs.io/en/latest/). Run `jupytext your-notebook.ipynb --to myst` to create a new MyST version of your file, `your-notebook.md`. Edit this file to include the relevant sections from the docs template. ``` From ebfff55b03783bc9207bbbb10e1c49bfb88ca04a Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Sat, 8 Mar 2025 14:06:31 -0500 Subject: [PATCH 13/17] Apply suggestions from code review by Melissa MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Melissa Weber Mendonça --- README.md | 4 ++-- docs/developers/contributing/documentation/index.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1b7d718e6..6e6d8a37f 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,8 @@ Please read our [contributing guide](https://napari.org/dev/developers/contribut ### quickstart: local setup * __Check the prerequisites__ - 1. Create a clean Python environment (e.g., with conda). - 1. In that environment, create an editable `napari` installation with the `docs` dependency group and a Qt backend. For example, after first forking and cloning the main `napari` project if you've not previously done so, run `python -m pip install -e "[.pyqt, docs]"` from your `napari/napari` clone directory. This will use the default Qt backend. + 1. Create a clean Python {{ python_version_range }} environment (e.g., with conda). + 1. In that environment, create an editable `napari` installation with the `docs` dependency group and a Qt backend. For example, after first forking and cloning the main `napari` project if you've not previously done so, run `python -m pip install -e ".[pyqt, docs]"` from your `napari/napari` clone directory. This will use the default Qt backend. 1. Fork *this* repository, `napari/docs`, and then clone your fork to your local machine. NB: you may want to name your fork e.g. `napari-docs` rather than just `docs`. * __Build__ locally * If you're building on Windows, a few extra steps are required; you can follow [this guide](https://napari.org/dev/developers/contributing/documentation/index.html#building-the-documentation-on-windows). diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 8a1214229..934ede25d 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -95,13 +95,13 @@ Since the API reference documentation (autogenerated from the napari code docstr ```bash python -m pip install -e ".[pyqt, docs]" ``` - This will use the default Qt backend. For other options, see [the napari installation guide](https://napari.org/stable/tutorials/fundamentals/installation.html#choosing-a-different-qt-backend). + This will use the default Qt backend. For other options, see [the napari installation guide](#choosing-a-different-qt-backend). ````{note} You can combine the documentation dependencies with [a development installation of napari](dev-installation) by having both `dev` and `docs` in the dependencies, e.g. `[pyqt, dev, docs]`. ```` -This setup, with these dependencies, will allow you to preview your document locally as it would appear on `napari.org`. +This setup, with these dependencies, will allow you to preview your document locally as it would appear on `napari.org`. ## 0. Before you start From c674cdd7d165b052a95dad1cbfbf07fb4ef3aff5 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Sat, 8 Mar 2025 14:33:02 -0500 Subject: [PATCH 14/17] Fixes --- README.md | 2 +- docs/developers/contributing/documentation/index.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6e6d8a37f..7c7ab1a26 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Please read our [contributing guide](https://napari.org/dev/developers/contribut ### quickstart: local setup * __Check the prerequisites__ - 1. Create a clean Python {{ python_version_range }} environment (e.g., with conda). + 1. Create a clean Python (>=3.10) environment (e.g., with conda). 1. In that environment, create an editable `napari` installation with the `docs` dependency group and a Qt backend. For example, after first forking and cloning the main `napari` project if you've not previously done so, run `python -m pip install -e ".[pyqt, docs]"` from your `napari/napari` clone directory. This will use the default Qt backend. 1. Fork *this* repository, `napari/docs`, and then clone your fork to your local machine. NB: you may want to name your fork e.g. `napari-docs` rather than just `docs`. * __Build__ locally diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 934ede25d..96f72985d 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -89,13 +89,13 @@ cd napari-docs/ Since the API reference documentation (autogenerated from the napari code docstrings) and the example gallery are sourced from the `napari/napari` repository, before you can build the documentation locally, you need: -- a clean `conda` environment—remember to activate it!; +- a clean virtual environment (e.g. `conda`) with Python {{ python_version_range }}—remember to activate it!; - a from-source, editable installation of napari with the optional `docs` dependencies and a Qt backend. Change directories to where you cloned napari and run, for example: ```bash python -m pip install -e ".[pyqt, docs]" ``` - This will use the default Qt backend. For other options, see [the napari installation guide](#choosing-a-different-qt-backend). + This will use the default Qt backend. For other options, see [the napari installation guide](../../../tutorials/fundamentals/installation.md#choosing-a-different-qt-backend). ````{note} You can combine the documentation dependencies with [a development installation of napari](dev-installation) by having both `dev` and `docs` in the dependencies, e.g. `[pyqt, dev, docs]`. From b954409e7bb0395636959eb5230d23f6baa96cfd Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Sat, 8 Mar 2025 14:36:51 -0500 Subject: [PATCH 15/17] Update add-examples --- docs/developers/contributing/documentation/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 96f72985d..20fd30993 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -583,6 +583,8 @@ Because our example gallery is built from Python scripts, you need to ensure thi block is present in all contributed examples. ```` +Finally, you can find the current example dependencies in [the `pyproject.toml` of napari/napari](https://github.com/napari/napari/blob/main/pyproject.toml) under the optional dependency `gallery`. If you add an example with a new dependency, be sure to include it here such that your example can be properly tested and built into the documentation. + ### Cross-referencing Gallery examples If you want to generate links to Gallery examples from anywhere in the docs, then the cross-referencing format you use will depend on the format of the doc you are writing. Note that the gallery examples live in `/gallery` despite being in `napari/examples` because [`docs/docs/conf.py`](https://github.com/napari/docs/blob/main/docs/conf.py) specifies that examples are built into the `gallery` directory. The [Sphinx cross-reference namespace](https://sphinx-gallery.github.io/stable/advanced.html#know-your-gallery-files) is generated with the `sphx_glr` prefix, then path separators are converted to underscores, for example `/gallery/add_image.py` becomes `_gallery_add_image.py` to get the end result `sphx_glr_gallery_add_image.py`. From a360b66ac2083f07d427b9f312a90ccd98214cee Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Sat, 8 Mar 2025 16:13:07 -0500 Subject: [PATCH 16/17] FIx the order. Install starts in napari/napari then you go to docs --- .../contributing/documentation/index.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 20fd30993..a9acf9103 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -65,7 +65,7 @@ For example, `C:\Users\myusername\Documents\GitHub\napari-docs` is a valid path, ``` You should first [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) -and then clone the [napari/napari](https://github.com/napari/napari) and the [napari/docs](https://github.com/napari/docs) repositories to your +and then clone both the [napari/napari](https://github.com/napari/napari) and the [napari/docs](https://github.com/napari/docs) repositories to your machine. To clone these repositories, you can follow any of the options in the [GitHub guide to cloning](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) (if you run into issues refer to [the troubleshooting guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors)). We recommend installing the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli) as it is easy to set up repository access permissions from the GitHub CLI and it comes with additional upside, such as the ability to checkout pull requests. After installing the `GitHub CLI` you can run: @@ -81,16 +81,16 @@ a local repository folder named `napari-docs`. Alternately, you could also rename the repository when forking `napari/docs` to `napari-docs` and then clone it via `gh repo clone /napari-docs`. ```` -Next, navigate to your local clone of the `napari/docs` repository: +Next, navigate to your local clone of the `napari/napari` repository: ```bash -cd napari-docs/ +cd napari ``` -Since the API reference documentation (autogenerated from the napari code docstrings) and the example gallery are sourced from the `napari/napari` repository, before you can build the documentation locally, you need: +Because the API reference documentation (autogenerated from the napari code docstrings), the example gallery, and the documentation dependencies are sourced from the `napari/napari` repository, before you can build the documentation locally you will need to install from the `napari/napari` repository. You will need: - a clean virtual environment (e.g. `conda`) with Python {{ python_version_range }}—remember to activate it!; -- a from-source, editable installation of napari with the optional `docs` dependencies and a Qt backend. Change directories to where you cloned napari and run, for example: +- a from-source, editable installation of napari with the optional `docs` dependencies and a Qt backend. From the `napari/napari` repository directory run, for example: ```bash python -m pip install -e ".[pyqt, docs]" @@ -101,7 +101,13 @@ Since the API reference documentation (autogenerated from the napari code docstr You can combine the documentation dependencies with [a development installation of napari](dev-installation) by having both `dev` and `docs` in the dependencies, e.g. `[pyqt, dev, docs]`. ```` -This setup, with these dependencies, will allow you to preview your document locally as it would appear on `napari.org`. +Once the installation is complete, you can proceed to the directory where you cloned the `napari/docs` respository: + +```bash +cd ../napari-docs +``` + + Here you will be able to build the documentation, allowing you to preview your document locally as it would appear on `napari.org`. ## 0. Before you start From 7ffac45cdface2befe1e5619e3ba2689cdf5a9d3 Mon Sep 17 00:00:00 2001 From: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com> Date: Sat, 8 Mar 2025 16:20:27 -0500 Subject: [PATCH 17/17] fix typo --- docs/developers/contributing/documentation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index a9acf9103..4778a8fe4 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -101,7 +101,7 @@ Because the API reference documentation (autogenerated from the napari code docs You can combine the documentation dependencies with [a development installation of napari](dev-installation) by having both `dev` and `docs` in the dependencies, e.g. `[pyqt, dev, docs]`. ```` -Once the installation is complete, you can proceed to the directory where you cloned the `napari/docs` respository: +Once the installation is complete, you can proceed to the directory where you cloned the `napari/docs` repository: ```bash cd ../napari-docs