Improve makefile

Makefile

@@ -6,27 +6,36 @@ ifeq ($(GALLERY_PATH),)
 GALLERY_PATH := ../../napari/examples
 endif
 
+mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST)))
+current_dir := $(dir $(mkfile_path))
+docs_dir := $(current_dir)docs
+
 clean:
 	echo clean
-	rm -rf docs/_build/
-	rm -rf docs/api/napari*.rst
-	rm -rf docs/_tags
-	rm -rf docs/gallery/
+	echo $(current_dir)
+	rm -rf $(docs_dir)/_build/
+	rm -rf $(docs_dir)/api/napari*.rst
+	rm -rf $(docs_dir)/gallery/*
+	rm -rf $(docs_dir)/_tags
 
 docs-install:
-	python -m pip install -qr requirements.txt
+	python -m pip install -qr $(current_dir)requirements.txt
 
 docs-build:
-	python docs/_scripts/prep_docs.py
+	python $(docs_dir)/_scripts/prep_docs.py
 	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b html docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH)
 
+docs-xvfb:
+	python $(docs_dir)/_scripts/prep_docs.py
+	NAPARI_APPLICATION_IPY_INTERACTIVE=0 xvfb-run --auto-servernum sphinx-build -b html docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH)
+
 docs: clean docs-install docs-build
 
 html: clean docs-build
 
 html-noplot: clean
-	python -qr docs/_scripts/prep_docs.py
+	python -qr $(docs_dir)/_scripts/prep_docs.py
 	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -D plot_gallery=0 -b html docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH)
 
 linkcheck-files:
-	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b linkcheck -D plot_gallery=0 --color docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH)
+	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b linkcheck -D plot_gallery=0 --color docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH)

docs/_scripts/prep_docs.py

@@ -7,16 +7,16 @@
 from pathlib import Path
 
 DOCS = Path(__file__).parent.parent.absolute()
-
+NPE = DOCS.parent.absolute() / 'npe2'
 
 def prep_npe2():
     #   some plugin docs live in npe2 for testing purposes
     from subprocess import check_call
 
-    check_call("rm -rf npe2".split())
-    check_call("git clone https://github.com/napari/npe2".split())
-    check_call([sys.executable, "npe2/_docs/render.py", DOCS / 'plugins'])
-    check_call("rm -rf npe2".split())
+    check_call(f"rm -rf {NPE}".split())
+    check_call(f"git clone https://github.com/napari/npe2 {NPE}".split())
+    check_call([sys.executable, f"{NPE}/_docs/render.py", DOCS / 'plugins'])
+    check_call(f"rm -rf {NPE}".split())
 
 
 def main():

docs/developers/documentation/index.md

@@ -22,8 +22,8 @@ you will require:
 - A [GitHub](https://github.com) account.
 
 You should first [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
-and clone the [napari/docs](https://github.com/napari/docs) repo to your
-machine, and navigate to the resulting folder:
+and clone the [napari/napari](https://github.com/napari/napari) and the [napari/docs](https://github.com/napari/docs) repo to your
+machine. Next, navigate to your local clone of the `napari/docs` repository:
 
 ```bash
 git clone git@github.com:<your-username>/docs.git napari-docs
@@ -36,25 +36,13 @@ a local repository folder named `napari-docs`. Alternately, you could also
 rename the repository when forking `napari/docs`.
 ````
 
-- **If you wish to add/amend documentation that does not contain code, you will
-  require a clean conda environment with napari docs dependencies installed.**
+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:
 
-  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;
+- a development installation of napari. 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`.
 
-  These dependencies will allow you to preview your document locally, as it
-  would appear on `napari.org`, and they will also install `jupytext`, which you
-  will need to contribute documents containing code or viewer interactions.
-
-- **If you wish to add/amend documentation that does contain code, you will also
-  require a clean conda environment with napari docs dependencies installed, but
-  with a development installation of napari.**
-
-  See the [contributor guide](dev-installation) for details. You should have
-  [Jupyter notebook](https://jupyter.org/) installed. Familiarity with Jupyter
-  notebooks (code cells and markdown cells) as well as using napari through a
-  Jupyter notebook is recommended.
+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.
 
 ## 0. Before you start
 
@@ -72,7 +60,7 @@ want to contribute. The paths are listed in parentheses below.
   in depth content about napari architecture, development choices and some complex features
 - [**Tutorials**](../../tutorials/index) (in [`napari/docs/tutorials`](https://github.com/napari/docs/tree/main/docs/tutorials)):
   detailed, reproducible step by step guides, usually combining multiple napari features to complete a potentially complex task
-- [**How-tos**](../../howtos/index) (in [`napari/docs/howtos/`](https://github.com/napari/docs/tree/main/docs/howtos)):
+- [**How-tos**](../../howtos/index) (in [`napari/docs/howtos`](https://github.com/napari/docs/tree/main/docs/howtos)):
   simple step by step guides demonstrating the use of common features
 - [**Getting started**](../../tutorials/start_index) (in [`napari/docs/tutorials/fundamentals`](https://github.com/napari/docs/tree/main/docs/tutorials/fundamentals):
   these documents are a mix of tutorials and how-tos covering the fundamentals of installing and working with napari for beginners