Add docs contributor's guide and docs template (napari#4168)

docs/_toc.yml

@@ -101,6 +101,10 @@ subtrees:
           - file: developers/testing
           - file: developers/docs
           - file: developers/translations
+          - file: developers/documentation/index
+            subtrees:
+            - entries:
+              - file: developers/documentation/docs_template
       - file: release/index
         subtrees:
         - entries:

docs/developers/documentation/docs_template.md

@@ -0,0 +1,147 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.10.3
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+theme:
+  intro: Template for adding new napari documentation
+---
+
+# Docs template
+
+This template will guide you to write a well formatted document and prepare it for contribution to napari.org.
+
+Edit this section to include a sentence or two introducing the tutorial, and include a time estimate for completion.
+
+## Prerequisites
+
+Fill out this section with a list of things the reader will need to successfully follow this document.
+Include things like:
+- python and/or napari version needed
+- links to any existing napari.org tutorials or how-to guides that can help the user fulfill these prerequisites
+- the level of python/napari knowledge required to follow this document
+    - try to be specific about what skills are needed e.g. 
+    'connecting callbacks to layer events' or 'using matplotlib to produce plots'
+- napari plugins that should be installed
+- python packages that should be installed (don't list napari or its dependencies)
+- links to sample data that can be used to follow your document
+  - **don't add this data to the repository**
+
+## Write your document
+Fill out the main content of the document - your explanation, how-to steps or tutorial.
+
+## Include pictures
+
+You should include pictures/videos, particularly when describing interactions with the viewer. If an action can be performed both through the viewer and through code, you should include both options. Keep accessibility in mind when adding images. Each image should be
+accompanied by complete and descriptive alt-text. If you're using arrows/circles to highlight portions of the image, make sure
+they contrast well against the background of the image.
+
+### Take screenshots of the viewer
+
+It's common for napari documentation to include code that has some effect in the napari Viewer e.g. adding layers,
+changing layer properties or using a plugin. These changes in the Viewer should be shown to the user, and this can
+be easily achieved in your notebook with napari's `nbscreenshot` utility. Follow these steps to include screenshots of the napari viewer and hide code cells.
+
+Note that wherever possible, auto-generated screenshots are *greatly* preferred to static images.
+
+#### 1. Use `nbscreenshot` for screenshots of the viewer
+
+This utility allows you to pass an active Viewer as a parameter and produces a screenshot of the Viewer at that 
+point in time. This screenshot will be displayed to the user in the notebook.
+
+```{code-cell} ipython3
+import napari
+from napari.utils import nbscreenshot
+
+viewer = napari.Viewer()
+# opens sample data and adds layer to the Viewer
+viewer.open_sample('napari', 'cells3d')
+
+# takes a screenshot and produces it as output for this cell
+nbscreenshot(viewer)
+```
+
+#### 2. Remove input cells
+
+As you can see, it's simple to produce screenshots of the napari Viewer in your notebooks. However, if you look through napari's
+existing documentation, none of the code cells include calls to `nbscreenshot`, yet the screenshots are still produced. In fact,
+it would be distracting if all the code cells included `nbscreenshot`, and might be frustrating for users who
+want to execute these notebooks in their own workflows.
+
+To avoid this frustration, we place calls to `nbscreenshot` in a removed cell in our notebooks.
+You can completely remove input (i.e. the code that's running) in a notebook cell by adding a `remove-input` tag to the cell metadata.
+
+How you add cell tags depends on how you're editing your notebook. 
+
+1. If you're working in Jupyter notebook,
+you can open up the Tags toolbar for your cell using `View -> Cell Toolbar -> Tags`. A toolbar
+will be added to the top right of your cell. You can then add any tags you want
+(e.g. `remove-input`) by typing into the text entry box of the toolbar and clicking `Add Tag`. 
+
+2. If you're editing a MyST Markdown file directly, you can add tags to your code blocks like so:
+
+```
+    ```{code-cell} python3
+    :tags: [remove-input]
+
+    print("Your code here")
+    ```
+```
+#### What to put in removed cells
+
+Alongside your call to `nbscreenshot`, you can also place other potentially distracting code in these tagged cells, 
+such as resizing the Viewer window or opening a menu. In general, if you're running code the reader isn't meant to run,
+this should be in a removed cell.
+The screenshot below is produced by the following code. The code that ran was removed using the `remove-input` tag.
+
+```python
+from napari.utils import nbscreenshot
+
+viewer.window._qt_window.resize(750, 550)
+viewer.dims.current_step = (25, 0, 1)
+nbscreenshot(viewer)
+```
+
+```{code-cell} python3
+:tags: [remove-input]
+
+from napari.utils import nbscreenshot
+
+viewer.window._qt_window.resize(750, 550)
+viewer.dims.current_step = (25, 0, 1)
+nbscreenshot(viewer)
+```
+
+Note how we've included the `nbscreenshot` import in this removed cell. Even though in the
+example above we imported `nbscreenshot` to show its functionality, you should place the
+import in a removed cell when you write your documentation.
+
+Here are some examples of settings you might want to use in a `remove-input` cell to make your screenshot look pretty:
+- window resizing (as above)
+- [toggling visible layers](napari.layers.Layer.visible)
+- [setting the slider position to a particular slice](napari.components.Dims.current_step)
+- [adjusting contrast limits](napari.layers.Image.contrast_limits)
+- [switching between 2D and 3D](napari.components.Dims.ndisplay)
+- switching to grid mode - use `viewer.grid.enabled = True` to enable grid mode
+- setting the [camera zoom](napari.components.Camera.zoom) or [angles](napari.components.Camera.angles)
+
+## Check that your notebook runs
+
+If your guide contains any code the user is expected to run, make sure that the notebook can be executed from start to finish without requiring any data or packages that you haven't listed in the prerequisites.
+
+## Use the Google developer's style guide
+
+The [Google writing style guide](https://developers.google.com/style/) should answer all your questions about when to italicise and when to bold, which
+words to capitalize in your headings (spoiler - we use sentence case for our headings) and other style conventions.
+
+## Next steps
+- Use this section to link to other (maybe more advanced?) tutorials, further reading on any complex topics you mentioned,
+or other relevant documentation
+- Now that you've written your document, you can proceed with [updating the TOC](./index.md#3-update-toc)

docs/developers/documentation/index.md

@@ -0,0 +1,154 @@
+# Contributing Documentation
+
+This guide will teach you how to submit new documents to napari's usage documentation.
+
+## Prerequisites
+
+- Familiarity with `git`
+- A [GitHub](https://github.com) account
+- A clean conda environment with napari docs dependencies installed 
+    - You can install these with `pip install "napari[docs]"`
+    - These dependencies will allow you to preview your document locally, as it would appear on `napari.org`
+    - They will also install `jupytext`, which you will need to contribute documents containing code or viewer interactions
+
+## 0. Before you start
+
+If you'd like to contribute a brand new document to our usage section, it might be worth [opening an issue](https://github.com/napari/napari/issues/new?assignees=&labels=documentation&template=documentation.md&title=)
+ on our repository first to discuss the content you'd like to see and get some early feedback from the community.
+The napari team can also suggest what type of document would be best suited, and whether there are already
+existing documents that could be expanded to include the content you think is lacking. 
+
+Examples of documents you might want to contribute are:
+
+- **Explanations** (in `napari/docs/guides`): in depth content about napari architecture, development choices and some complex features 
+- **Tutorials** (in `napari/docs/tutorials`): detailed, reproducible step by step guides, usually combining multiple napari features to complete a potentially complex task
+- **How-tos** (in `napari/docs/howtos/`): simple step by step guides demonstrating the use of common features
+- **Getting started** (in `napari/docs/tutorials/fundamentals`): these documents are a mix of tutorials and how-tos covering the fundamentals of installing and working with napari for beginners
+
+```{admonition} Got materials for a workshop?
+:class: tip
+
+If you already have teaching materials e.g. recordings, slide decks or jupyter notebooks
+hosted somewhere, you can add links to these on our [napari workshops](../../further-resources/napari-workshops.md) page.
+```
+
+If you are writing a document whose content is mostly text,
+you can write a plain markdown document and skip straight to [Step #3 - Update TOC](#3-update-toc).
+If you are writing a how-to guide or tutorial that requires executing code or working with the napari viewer, follow
+the steps below to prepare your document.
+
+### Prerequisites for contributing documentation with code
+
+- [Jupyter notebook](https://jupyter.org/) installed
+- Familiarity with Jupyter notebooks (code cells and markdown cells)
+- Familiarity with using napari through a Jupyter notebook
+
+## 1. Download our template
+
+Our goal is that all tutorials and how-tos are easily downloadable and executable by our users. 
+This helps ensure that they are reproducible and makes them easier to maintain. 
+We therefore provide a notebook template for our documents.
+
+[Jupyter notebooks](https://jupyter.org/) are a great option for our documents, because they allow you to easily combine code and well formatted text in markdown. 
+However, their [raw JSON format](https://numpy.org/numpy-tutorials/content/pairing.html#background) is not great for version control, so we use [MyST Markdown](https://myst-parser.readthedocs.io/en/latest/) documents in our repository and on napari.org.  
+
+Fork and clone [our repository](https://github.com/napari/napari), and make a copy of `napari/docs/developers/documentation/docs_template.md`. 
+You can edit the template directly in 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 file, `your-notebook.md`. Edit this file to
+include the relevant sections from the docs template.
+```
+## 2. Write your document
+
+Follow the template to write your document. Inside the template you'll also find handy tips for taking screenshots of the viewer,
+hiding code cells, using style guides and what to include in the required prerequisites section.
+
+## 3. Update TOC
+
+Add your document to the correct folder based on its content (see the [list above](#0-before-you-start) for common locations), and update `napari/docs/_toc.yml`. 
+
+If you're adding a document
+to an existing group, simply add a new `- file:` entry in the appropriate spot. For example, if I wanted to add 
+a `progress_bars.md` how to guide, I would place it in `napari/docs/howtos` and update `_toc.yml` as below:
+
+```yaml
+- file: howtos/index
+subtrees:
+- titlesonly: True
+entries:
+- file: howtos/layers/index
+subtrees:
+- titlesonly: True
+    entries:
+    - file: howtos/layers/image
+    - file: howtos/layers/labels
+    - file: howtos/layers/points
+    - file: howtos/layers/shapes
+    - file: howtos/layers/surface
+    - file: howtos/layers/tracks
+    - file: howtos/layers/vectors
+- file: howtos/connecting_events
+- file: howtos/napari_imageJ
+- file: howtos/docker
+- file: howtos/perfmon
+- file: howtos/progress_bars # added
+```
+
+To create a new subheading, you need a `subtrees` entry. For example, if I wanted to add `geo_tutorial1.md` and `geo_tutorial2.md`
+to a new `geosciences` subheading in tutorials, I would place my documents in a new folder `napari/docs/tutorials/geosciences`,
+together with an `index.md` that describes what these tutorials would be about, and then update `_toc.yml` as below:
+
+```yaml
+- file: tutorials/index
+subtrees:
+- entries:
+    - file: tutorials/annotation/index
+    subtrees:
+    - entries: 
+        - file: tutorials/annotation/annotate_points
+    - file: tutorials/processing/index
+    subtrees:
+    - entries:
+        - file: tutorials/processing/dask
+    - file: tutorials/segmentation/index
+    subtrees:
+    - entries:
+        - file: tutorials/segmentation/annotate_segmentation
+    - file: tutorials/tracking/index
+    subtrees:
+    - entries:
+        - file: tutorials/tracking/cell_tracking
+    - file: tutorials/geosciences/index                 # added
+    subtrees:                                           # added
+    - entries:                                          # added
+        - file: tutorials/geosciences/geo_tutorial1     # added
+        - file: tutorials/geosciences/geo_tutorial2     # added
+```
+
+## 4. Preview your document
+
+Once you've added your document to the `docs` folder and updated the `_toc.yml`, you can preview the website
+ locally by running `make docs` from the root of
+the `napari` repository (assuming you've installed the [docs prerequisites](#prerequisites)).
+
+```bash
+make docs
+```
+
+The rendered HTML will be placed in `napari/docs/_build`. Find `index.html` in this folder and drag it
+into a browser to preview the website with your new document.
+
+## 5. Submit your pull request
+
+Once you have written and previewed your document, it's time to open a pull request to [napari's main repository](https://github.com/napari/napari) and contribute it to our codebase. 
+If you've never opened a Pull Request, you may find [this guide](https://www.digitalocean.com/community/tutorials/how-to-create-a-pull-request-on-github) useful.
+You can also reach out to us on [zulip](https://napari.zulipchat.com/#narrow/stream/212875-general) for assistance!
+
+Not sure where to place your document or update `_toc.yml`? Make a best guess and open the pull request - the napari team will
+help you edit your document and find the right spot!

setup.cfg

@@ -129,6 +129,7 @@ docs =
     %(all)s
     sphinx_autodoc_typehints==1.12.0
     Jinja2
+    jupytext
     sphinx-tabs
     sphinx-panels
     myst-nb