Added GALLERY_PATH option for building examples gallery

Author: melissawm

.github/workflows/build_docs.yml

@@ -46,7 +46,7 @@ jobs:
           GOOGLE_CALENDAR_ID: ${{ secrets.GOOGLE_CALENDAR_ID }}
           GOOGLE_CALENDAR_API_KEY: ${{ secrets.GOOGLE_CALENDAR_API_KEY }}
         with:
-          run: make docs
+          run: make docs GALLERY_PATH=../examples/
 
       - name: Upload artifact
         uses: actions/upload-artifact@v2

Makefile

@@ -1,5 +1,11 @@
 .PHONY: docs clean
 
+# Gallery path must be given relative to the docs/ folder
+
+ifeq ($(GALLERY_PATH),)
+GALLERY_PATH := ../../napari/examples
+endif
+
 clean:
 	echo clean
 	rm -rf docs/_build/
@@ -12,15 +18,15 @@ docs-install:
 
 docs-build:
 	python docs/_scripts/prep_docs.py
-	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b html docs/ docs/_build
+	NAPARI_APPLICATION_IPY_INTERACTIVE=0 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
-	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -D plot_gallery=0 -b html docs/ docs/_build
+	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
+	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/conf.py

@@ -190,7 +190,8 @@ def reset_napari_theme(gallery_conf, fname):
     qtgallery.reset_qapp(gallery_conf, fname)
 
 sphinx_gallery_conf = {
-    'examples_dirs': '../../napari/examples',  # path to your example scripts
+    #'examples_dirs': '../../napari/examples',  # path to your example scripts
+                                                # this value is set in the Makefile
     'gallery_dirs': 'gallery',  # path to where to save gallery generated output
     'filename_pattern': '/*.py',
     'ignore_pattern': 'README.rst|/*_.py',

docs/developers/documentation/index.md

@@ -215,11 +215,37 @@ clone of the `napari/docs` repository (assuming you've installed the
 make docs
 ```
 
-```{note}
+````{note}
 The `make docs` command above assumes your have a local clone of the
 [`napari/napari`](https://github.com/napari/napari) repo at the same level as
-the `napari/docs` clone.
+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=<path-to-examples-folder>
+```
+
+The `GALLERY_PATH` option must be given relative to the `docs` folder. If your
+folder structure is 
+
 ```
+├── napari-docs
+│   └── docs
+├── napari
+│   ├── binder
+│   ├── examples
+│   ├── napari
+│   ├── napari_builtins
+│   ├── resources
+│   └── tools
+```
+
+Then the command would be
+```bash
+make docs GALLERY_PATH=../../napari/examples
+```
+
+````
 
 The rendered HTML will be placed in `docs/_build`. Find `index.html` in this
 folder and drag it into a browser to preview the website with your new document.