diff --git a/docs/developers/contributing/documentation/index.md b/docs/developers/contributing/documentation/index.md index e78fed1f4..aefc57ffd 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,31 @@ 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. +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 +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.