From 0af19fb84744ec0b8759464d77002932bac45cfb Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Mon, 20 Apr 2026 16:38:19 -0500 Subject: [PATCH 1/2] add more info about example tags and _.py --- .../contributing/documentation/index.md | 24 ++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index e78fed1f4..8bdbdb429 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -798,7 +798,7 @@ If you prefer or need to use `make` (e.g., for headless builds), see the [advanc All of the examples in the [examples Gallery](gallery) are Python scripts that live under [the `examples` folder of the napari repository](https://github.com/napari/napari/tree/main/examples). -Because of how this gallery is built, every such Python script needs a docstring +Any example that should appear in the generated gallery needs a docstring containing at least a title (following the `.rst` format of docstrings in Python) and one or more _tags_. This ensures the example will be shown in the correct place in the table of contents for the gallery (see, for example, the @@ -834,6 +834,28 @@ use of the `.. tags::` directive. In this case, the only tag associated with this example is `visualization-basic`. Multiple tags can be separated with a comma. +Tags are generated into the [](tagoverview) pages by `sphinx-tags`. They are +descriptive labels, not execution flags. +Tags do not hide an example from the gallery or change how it is built. +If an example should stay out of the public gallery, use the `*_.py` naming +convention instead as this will prevent it from being built. + +Before creating a new tag, check [](tagoverview) and reuse an existing tag +when possible. New tags automatically create new tag pages, so the tag set is +easier to navigate when it stays small and intentional. + +The most common tags currently mean: + +- `visualization-basic`: introductory examples centered on core viewer or layer usage +- `visualization-nD`: examples that focus on higher-dimensional, 3D, or multiscale data +- `visualization-advanced`: more complex rendering, transforms, or advanced viewer composition +- `gui`: Qt widgets, dock widgets, window integration, or other UI customization +- `interactivity`: mouse callbacks, key bindings, and interactive viewer behavior +- `analysis`: analysis, annotation, or measurement-oriented workflows +- `layers`: examples that emphasize layer properties or layer interactions +- `experimental`: examples that rely on experimental napari APIs or behavior that may still change +- `historical`: legacy or reference examples that remain useful to publish, but are not the best starting point for new code + Note that the examples are `.py` source files, and any outputs and images will be autogenerated when the documentation site is built. From 1bcdf136bae3640b5c05e276b68edf091d5aa283 Mon Sep 17 00:00:00 2001 From: Tim Monko Date: Thu, 23 Apr 2026 17:33:27 -0500 Subject: [PATCH 2/2] Apply suggestion from @willingc --- docs/developers/contributing/documentation/index.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index 8bdbdb429..aefc57ffd 100644 --- a/docs/developers/contributing/documentation/index.md +++ b/docs/developers/contributing/documentation/index.md @@ -837,8 +837,11 @@ comma. Tags are generated into the [](tagoverview) pages by `sphinx-tags`. They are descriptive labels, not execution flags. Tags do not hide an example from the gallery or change how it is built. -If an example should stay out of the public gallery, use the `*_.py` naming -convention instead as this will prevent it from being built. +To stop displaying an example in the public gallery, +add an underscore _ after the example's name. +microscopy_example.py would be displayed in the public gallery; +while, microscopy_example_.py would not be displayed in the public gallery +due to the trailing underscore in the name. Before creating a new tag, check [](tagoverview) and reuse an existing tag when possible. New tags automatically create new tag pages, so the tag set is