From e9e874fdd88ab9cb7bc4b12d894cd4b6749b059c Mon Sep 17 00:00:00 2001 From: Lucy Liu Date: Tue, 23 Jan 2024 23:47:58 +1100 Subject: [PATCH] Use reference labels instead of paths (#301) # References and relevant issues towards #296 # Description Uses references labels instead of paths. A few notes: * I have left all the paths inside `docs/plugins/virtual_environment_docs` as they just reference files within that folder so I think we're safe * I did not know how to deal with `gallery/` links. Does sphinx-tag automatically generate the gallery index/readme page..? * Standardised use of `-` between words in reference labels * Removed `napari` from some reference labels, as there is no 'plugin' equivalent thus its obvs it is about napari * Images! - We still have a lot of relative paths to image/animation files. These would ideally be absolute paths, meaning they would be fine as long as the images stay in the same folder, but I could not be bothered. Maybe will leave this to be fixed when needed.... --- docs/community/governance.md | 2 +- docs/community/index.md | 4 ++-- docs/community/meeting_schedule.md | 2 ++ docs/developers/architecture/napari_models.md | 2 +- docs/developers/benchmarks.md | 2 +- docs/developers/contributing.md | 8 ++++--- docs/developers/core_dev_guide.md | 8 +++---- .../documentation/docs_deployment.md | 2 +- .../developers/documentation/docs_template.md | 2 ++ docs/developers/documentation/index.md | 16 ++++++++------ docs/developers/index.md | 22 ++++++++++--------- docs/developers/maintenance.md | 2 ++ docs/developers/profiling.md | 2 ++ docs/developers/release.md | 2 ++ docs/further-resources/napari-workshops.md | 5 +++-- docs/guides/index.md | 4 ++-- docs/guides/layers.md | 6 ++--- docs/howtos/docker.md | 2 ++ docs/howtos/headless.md | 2 ++ docs/howtos/index.md | 17 +++++++------- docs/howtos/layers/index.md | 2 +- docs/howtos/layers/labels.md | 10 ++++++++- docs/howtos/layers/points.md | 8 +++---- docs/howtos/layers/surface.md | 14 ++++++------ docs/howtos/layers/tracks.md | 2 ++ docs/howtos/napari_imageJ.md | 2 ++ docs/index.md | 2 +- docs/naps/0-nap-process.md | 2 +- .../advanced_topics/npe2_migration_guide.md | 14 ++++++------ .../building_a_plugin/best_practices.md | 2 ++ .../building_a_plugin/debug_plugins.md | 4 ++-- .../plugins/building_a_plugin/first_plugin.md | 14 ++++++------ docs/plugins/building_a_plugin/guides.md | 2 +- docs/plugins/testing_and_publishing/test.md | 4 +++- .../1-pythons-assert-keyword.md | 12 +++++----- .../2-pytest-testing-frameworks.md | 16 ++++++++------ .../3-readers-and-fixtures.md | 12 +++++----- .../testing_workshop_docs/4-test-coverage.md | 10 +++++---- docs/plugins/testing_workshop_docs/index.md | 10 ++++----- .../testing-resources.md | 2 ++ docs/roadmaps/0_3.md | 2 +- docs/roadmaps/0_3_retrospective.md | 2 +- docs/roadmaps/0_4.md | 4 ++-- docs/roadmaps/index.md | 2 ++ docs/tutorials/annotation/annotate_points.md | 4 +++- .../tutorials/fundamentals/getting_started.md | 16 +++++++------- docs/tutorials/fundamentals/installation.md | 9 ++++---- docs/tutorials/fundamentals/quick_start.md | 14 ++++++------ docs/tutorials/fundamentals/viewer.md | 15 ++++++------- docs/tutorials/index.md | 6 ++--- docs/tutorials/processing/dask.md | 2 ++ docs/tutorials/segmentation/index.md | 2 +- docs/tutorials/start_index.md | 10 +++++---- docs/tutorials/tracking/cell_tracking.md | 6 ++--- docs/usage.md | 2 ++ 55 files changed, 204 insertions(+), 148 deletions(-) diff --git a/docs/community/governance.md b/docs/community/governance.md index bd105d120..2b7f65912 100644 --- a/docs/community/governance.md +++ b/docs/community/governance.md @@ -42,7 +42,7 @@ among other possibilities. Any community member can become a contributor, and all are encouraged to do so. By contributing to the project, community members can directly help to shape its future. -Contributors are encouraged to read the [contributing guide](napari-contributing). +Contributors are encouraged to read the [contributing guide](contributing-code). ### Core developers diff --git a/docs/community/index.md b/docs/community/index.md index 524947910..83152d079 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -7,7 +7,7 @@ examples, you are welcome to help develop and improve napari. To ask questions and interact with the team, you can join our [zulip chat](https://napari.zulipchat.com/login/) or participate in our -[meetings](./meeting_schedule). +[meetings](meeting-schedule). If you are interested in contributing, check out our -[contributing guide](../developers/index). +[contributing guide](contributing). diff --git a/docs/community/meeting_schedule.md b/docs/community/meeting_schedule.md index ec6bf4ff6..5669410d9 100644 --- a/docs/community/meeting_schedule.md +++ b/docs/community/meeting_schedule.md @@ -1,3 +1,5 @@ +(meeting-schedule)= + # Meeting schedule We hold regular meetings, the timings of which are available on our [public calendar](https://calendar.google.com/calendar/embed?src=c_35r93ec6vtp8smhm7dv5uot0v4%40group.calendar.google.com). diff --git a/docs/developers/architecture/napari_models.md b/docs/developers/architecture/napari_models.md index 2511d45f5..dad2157ba 100644 --- a/docs/developers/architecture/napari_models.md +++ b/docs/developers/architecture/napari_models.md @@ -29,7 +29,7 @@ The separation of the Python models from viewer GUI code allows: used * tests to be easily run headlessly * the Python models to be run headlessly (see - [Running napari headlessly](../howtos/headless) for more) + [Running napari headlessly](headless) for more) ## Python models and events diff --git a/docs/developers/benchmarks.md b/docs/developers/benchmarks.md index e40f00b8c..5e6f87c86 100644 --- a/docs/developers/benchmarks.md +++ b/docs/developers/benchmarks.md @@ -1,4 +1,4 @@ -(napari-benchmarks)= +(benchmarks)= # Benchmarks While not mandatory for most pull requests, we ask that performance related diff --git a/docs/developers/contributing.md b/docs/developers/contributing.md index 590780254..c50e665b5 100644 --- a/docs/developers/contributing.md +++ b/docs/developers/contributing.md @@ -1,11 +1,11 @@ -(napari-contributing)= +(contributing-code)= # Contributing guide We welcome your contributions! Please see the provided steps below and never hesitate to contact us. If you are a new user, we recommend checking out the detailed [Github Docs](https://docs.github.com/en). -You can see the general direction for napari development and possible work plans in our current [Roadmap](../roadmaps/index.md). +You can see the general direction for napari development and possible work plans in our current [Roadmap](roadmaps). (dev-installation)= ## Setting up a development installation @@ -55,10 +55,12 @@ In order to make changes to `napari`, you will need to [fork](https://docs.githu 4. Install the package in editable mode, along with all of the developer tools. + ```{note} If you only want to use napari, you can install it on most macOS, Linux and Windows systems with Python {{ python_version_range }} by following the directions on the - [instructions page](../tutorials/fundamentals/installation.md#install-as-python-package-recommended). + [instructions page](install-python-package). + ``` napari supports different Qt backends, and you can choose which one to install and use. diff --git a/docs/developers/core_dev_guide.md b/docs/developers/core_dev_guide.md index f15f494d4..407bf26a7 100644 --- a/docs/developers/core_dev_guide.md +++ b/docs/developers/core_dev_guide.md @@ -45,7 +45,7 @@ When merging, use GitHub's to ensure a clean git history. You should also continue to make your own pull requests as before and in accordance -with the [general contributor guide](napari-contributing). These pull requests still +with the [general contributor guide](contributing-code). These pull requests still require the approval of another core developer before they can be merged. ## Reviewing @@ -80,7 +80,7 @@ consult back with our [mission and values](mission-and-values). 2. **Performance and benchmarks:** As `napari` targets scientific applications that often involve large multidimensional datasets, high performance is a key value of `napari`. While every new feature won't scale equally to all sizes of data, keeping in mind performance -and our [benchmarks](napari-benchmarks) during a review may be important, and you may +and our [benchmarks](benchmarks) during a review may be important, and you may need to ask for benchmarks to be run and reported or new benchmarks to be added. 3. **APIs and stability:** Coding users and plugin developers will make @@ -154,11 +154,11 @@ For details on how the documentation and website are built, see As a core member, you should be familiar with community and developer resources such as: -- Our [contributor guide](napari-contributing). +- Our [contributor guide](contributing-code). - Our [code of conduct](napari-coc). - Our [governance](napari-governance). - Our [mission and values](mission-and-values). -- Our [benchmarking guide](napari-benchmarks). +- Our [benchmarking guide](benchmarks). - [PEP8](https://peps.python.org/pep-0008/) for Python style. - [PEP257](https://peps.python.org/pep-0257/) and the [NumPy documentation guide](https://numpy.org/devdocs/dev/howto-docs.html#documentation-style) diff --git a/docs/developers/documentation/docs_deployment.md b/docs/developers/documentation/docs_deployment.md index 0a172fed8..d18e7ae6b 100644 --- a/docs/developers/documentation/docs_deployment.md +++ b/docs/developers/documentation/docs_deployment.md @@ -3,7 +3,7 @@ ```{note} This guide is intended for napari core contributors and is not required reading for regular contributors. If you're looking for information on how to contribute -to the documentation, see [](docs_contributing_guide). +to the documentation, see [](contributing-docs). ``` The napari documentation and website sources are spread over three repositories, diff --git a/docs/developers/documentation/docs_template.md b/docs/developers/documentation/docs_template.md index 2e1522951..9705a5275 100644 --- a/docs/developers/documentation/docs_template.md +++ b/docs/developers/documentation/docs_template.md @@ -14,6 +14,8 @@ theme: intro: Template for adding new napari documentation --- +(docs-template)= + # Docs template This template will guide you to write a well formatted document and prepare it for contribution to napari.org. diff --git a/docs/developers/documentation/index.md b/docs/developers/documentation/index.md index 4f85550af..282c57774 100644 --- a/docs/developers/documentation/index.md +++ b/docs/developers/documentation/index.md @@ -1,4 +1,4 @@ -(docs_contributing_guide)= +(contributing-docs)= # Contributing Documentation This guide will teach you how to submit new documents to napari's usage @@ -106,13 +106,13 @@ that could be expanded to include the content you think is lacking. Go to your local `napari/docs` folder to find examples of documents you might want to contribute. The paths are listed in parentheses below. -- [**Explanations**](../../guides/index) (in [`napari/docs/guides`](https://github.com/napari/docs/tree/main/docs/guides)): +- [**Explanations**](explanations) (in [`napari/docs/guides`](https://github.com/napari/docs/tree/main/docs/guides)): 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)): +- [**Tutorials**](tutorials) (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**](how-tos) (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)): +- [**Getting started**](getting-started) (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 The [**Examples gallery**](../../gallery) sources are in the [main `napari/napari` repository](https://github.com/napari/napari/tree/main/examples) @@ -122,9 +122,11 @@ and show code examples of how to use napari. :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. +hosted somewhere, you can add links to these on our [napari workshops](workshops) page. ``` +(contributing-docs-step-one)= + ## 1. Write your documentation Our goal is that all tutorials and how-tos are easily downloadable and @@ -138,7 +140,7 @@ documents in our repository and on [napari.org](https://napari.org). If you are amending existing documentation, you can do so in your preferred text editor. If you wish to add a new tutorial or a how-to, we recommend you use our -[template](./docs_template). Inside the template you'll find handy tips for +[template](docs-template). Inside the template you'll find handy tips for taking screenshots of the viewer, hiding code cells, using style guides and what to include in the required prerequisites section. diff --git a/docs/developers/index.md b/docs/developers/index.md index 98ee32802..beebc5fdc 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -1,21 +1,23 @@ +(contributing)= + # Contributing Here you can find resources about the contributing workflow for both code to napari core and documentation of the project, as well as information for onboarding of new core developers. -You can see the general direction for napari development and possible work plans in our current [Roadmap](../roadmaps/index.md). +You can see the general direction for napari development and possible work plans in our current [Roadmap](roadmaps). ## For contributors -- [Contributing guide](./contributing) -- [Contributing documentation](./documentation/index) -- [Translations](./translations) -- [Testing](./testing) -- [Profiling](./profiling) -- [Benchmarks](./benchmarks) +- [Contributing guide](contributing-code) +- [Contributing documentation](contributing-docs) +- [Translations](translations) +- [Testing](napari-testing) +- [Profiling](profiling) +- [Benchmarks](benchmarks) ## For core developers -- [Core Developer guide](./core_dev_guide) -- [Release guide](./release) -- [Maintenance](./maintenance) +- [Core Developer guide](core-dev-guide) +- [Release guide](release) +- [Maintenance](maintenance) diff --git a/docs/developers/maintenance.md b/docs/developers/maintenance.md index be34ff366..ae942a680 100644 --- a/docs/developers/maintenance.md +++ b/docs/developers/maintenance.md @@ -1,3 +1,5 @@ +(maintenance)= + # Maintenance This document describes maintenance tasks that need to be performed from time to time. Its purpose is to avoid relying on personal memory alone, and it should be updated regularly. diff --git a/docs/developers/profiling.md b/docs/developers/profiling.md index ca727a2a1..3bbb41fc7 100644 --- a/docs/developers/profiling.md +++ b/docs/developers/profiling.md @@ -1,3 +1,5 @@ +(profiling)= + # Profiling In contrast to performance tracing, profiling does not provide information diff --git a/docs/developers/release.md b/docs/developers/release.md index edd62d87b..cb2ee9e18 100644 --- a/docs/developers/release.md +++ b/docs/developers/release.md @@ -1,3 +1,5 @@ +(release)= + # Release guide This guide documents `napari`'s release process. diff --git a/docs/further-resources/napari-workshops.md b/docs/further-resources/napari-workshops.md index 4e4062bc1..8f4448d73 100644 --- a/docs/further-resources/napari-workshops.md +++ b/docs/further-resources/napari-workshops.md @@ -1,4 +1,4 @@ -(napari-workshops)= +(workshops)= # napari workshops There have been many workshops and tutorials given about napari. @@ -14,7 +14,8 @@ as a starting point. If you have organized a napari workshop and would like to see it featured here in this page, you can -[send a Pull Request to the napari/docs repository](../developers/documentation/index.md) +[send a Pull Request](contributing-docs-step-one) to the +[napari/docs repository](https://github.com/napari/docs) or contact the core developers on [zulip chat](https://napari.zulipchat.com/login/). ``` diff --git a/docs/guides/index.md b/docs/guides/index.md index ab6adac4f..9c7327136 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -3,8 +3,8 @@ ```{note} These pages describe advanced usage and how napari works internally. If you are -just getting started, check out our [tutorials](../tutorials/index.md) or -[how-to guides](../howtos/index.md) instead. +just getting started, check out our [tutorials](tutorials) or +[how-to guides](how-tos) instead. ``` ## Advanced usage diff --git a/docs/guides/layers.md b/docs/guides/layers.md index e07e19774..dd27b1dec 100644 --- a/docs/guides/layers.md +++ b/docs/guides/layers.md @@ -1,7 +1,7 @@ (layers-glance)= # Layers at a glance -[Layers](napari.layers) are the basic viewable objects that can be added to a +{class}`~napari.layers` are the basic viewable objects that can be added to a viewer. **napari** supports seven main different layer types: `Image`, `Labels`, `Points`, `Shapes`, `Surface`, `Tracks` and `Vectors`. Each of the layer types corresponds to a different data type, visualization, and interactivity. You can @@ -24,9 +24,9 @@ viewer.add_image(data, name='astronaut') To learn more about the layers available, see the [Layers documentation](napari.layers). To learn about how to use the layers currently supported by napari, check out the -[Using layers how-to guides](../../howtos/layers/index). For a gentle +[Using layers how-to guides](using-layers). For a gentle introduction, check out the -[Layer list section in the napari viewer tutorial](layer_list). +[Layer list section in the napari viewer tutorial](layer-list). ## Layer visibility diff --git a/docs/howtos/docker.md b/docs/howtos/docker.md index 6fea186f0..522970259 100644 --- a/docs/howtos/docker.md +++ b/docs/howtos/docker.md @@ -1,3 +1,5 @@ +(docker)= + # Napari in Docker ## Build diff --git a/docs/howtos/headless.md b/docs/howtos/headless.md index e97bbec4a..0a7fc7b1d 100644 --- a/docs/howtos/headless.md +++ b/docs/howtos/headless.md @@ -1,3 +1,5 @@ +(headless)= + # Running napari headlessly Running napari headlessly (without opening a napari GUI interface) may be diff --git a/docs/howtos/index.md b/docs/howtos/index.md index fe49d5f42..76929cc26 100644 --- a/docs/howtos/index.md +++ b/docs/howtos/index.md @@ -4,23 +4,22 @@ These guides show you how to complete tasks with napari. They assume you have already installed **napari**, know how to launch the viewer, and are familiar with its layout. For help with installation see our -[installation tutorial](../tutorials/fundamentals/installation). For help +[installation tutorial](installation). For help getting started with the viewer see our -[Getting started guide](../tutorials/fundamentals/getting_started). For +[How to launch napari guide](launch). For help understanding the organisation of the viewer, including things like the layers list, the layer properties widgets, the layer control panels, and the -dimension sliders see our [napari viewer](../tutorials/fundamentals/viewer) +dimension sliders see our [napari viewer](viewer-tutorial) tutorial. -- [Using layers](layers/index): Learn about how to use the layers currently +- [Using layers](using-layers): Learn about how to use the layers currently supported by napari. - [Extending napari](extending-napari): Learn how to extend napari by adding widgets and connecting callbacks. -- [napari + ImageJ how-to guide](./napari_imageJ): Learn about how to use napari -and ImageJ simultaneously. -- [napari in Docker](./docker): Learn about using napari in docker. -- [Performance monitoring](./perfmon): Learn about how to monitor napari +- [napari + ImageJ how-to guide](napari-imagej): Learn about how to use napari +- [napari in Docker](docker): Learn about using napari in docker. +- [Performance monitoring](perfmon): Learn about how to monitor napari performance and diagnose potential problems. -- [napari headless](./headless): Tips on how to run napari headlessly. +- [napari headless](headless): Tips on how to run napari headlessly. - [Themes](themes): Changing appearance of the napari GUI with your own theme and sharing your theme via a plugin. diff --git a/docs/howtos/layers/index.md b/docs/howtos/layers/index.md index b05dff830..c1424adff 100644 --- a/docs/howtos/layers/index.md +++ b/docs/howtos/layers/index.md @@ -12,4 +12,4 @@ Each of these guides has a section on how to manipulate the layers using the GUI controls and a section on how to manipulate them programmatically. For a high-level overview of the napari Layers, see -[Layers at a glance](../../guides/layers). \ No newline at end of file +[Layers at a glance](layers-glances). \ No newline at end of file diff --git a/docs/howtos/layers/labels.md b/docs/howtos/layers/labels.md index 37c221455..430339ab6 100644 --- a/docs/howtos/layers/labels.md +++ b/docs/howtos/layers/labels.md @@ -414,7 +414,15 @@ and [zarr arrays](https://zarr.readthedocs.io/en/stable/api/core.html). A Because the `labels` layer subclasses the `image` layer, it inherits the great properties of the `image` layer, like supporting lazy loading and multiscale images for big data layers. For more information about both these concepts see -the details in [Using the image layer](./image). +the details in the [image layer guide](image-layer). + +## Creating a new labels layer + +As you can edit a `Labels` layer using the paintbrush and fill bucket, it is +possible to create a brand-new empty labels layers by clicking the new labels +layer button above the layers list. The shape of the new labels layer will match +the size of any currently existing image layers, allowing you to paint on top of +them. ```{admonition} Want to save without compression? :class: tip diff --git a/docs/howtos/layers/points.md b/docs/howtos/layers/points.md index 4176ec93a..ee4527aaf 100644 --- a/docs/howtos/layers/points.md +++ b/docs/howtos/layers/points.md @@ -30,9 +30,9 @@ all the points simultaneously. Each data point can have annotations associated with it using the `Points.properties` dictionary. These properties can be used to set the face and edge colors of the points. For example, when displaying points of different -classes/types, one could automatically set the color of the individual points by -their respective class/type. For more details on point properties, see -[](#setting-point-edge-and-face-color-with-properties) below or the +classes/types, one could automatically set color the individual points by their +respective class/type. For more details on point properties, see +[](#setting-point-edge-and-face-color-with-properties) or [point annotation tutorial](../../tutorials/annotation/annotate_points). ## Creating and editing the `points` layer using the GUI @@ -266,7 +266,7 @@ name of the property and the values are NumPy arrays with a value for each point (i.e., length N for N points in `Points.data`). As we will see below, we can use the values in a property to set the display properties of the points (e.g., face color or edge color). To see the points properties in action, please see the -[Point annotation tutorial](../../tutorials/annotation/annotate_points). +[Point annotation tutorial](annotating-points). ### Non-editable mode diff --git a/docs/howtos/layers/surface.md b/docs/howtos/layers/surface.md index 761353cf6..f224d65ad 100644 --- a/docs/howtos/layers/surface.md +++ b/docs/howtos/layers/surface.md @@ -144,13 +144,13 @@ object. You can list all the available colormaps using `layer.colormaps`. It is also possible to create your own colormaps using vispy's `vispy.color.Colormap` object, see it's full [documentation here](https://vispy.org/api/vispy.color.colormap.html#vispy.color.colormap.Colormap). -For more detail see [](./image). +For more detail see the [image layer guide](image-layer). ## Adjusting contrast limits -The vertex values of the `surface` layer get mapped through its colormap -according to values called `contrast limits`. These are a 2-tuple of values -defining how what values get applied the minimum and maximum of the colormap and -follow the same principles as the `contrast_limits` described in [](./image). -They are also accessible through the same keyword arguments, properties, and GUI -layer controls as in the image layer. +The vertex values of the `surface` layer get mapped through its colormap according +to values called `contrast limits`. These are a 2-tuple of values defining how +what values get applied the minimum and maximum of the colormap and follow the +same principles as the `contrast_limits` described in the +[image layer guide](image-layer). They are also accessible through the same keyword +arguments, properties, and GUI layer controls as in the image layer. diff --git a/docs/howtos/layers/tracks.md b/docs/howtos/layers/tracks.md index 28d11c54c..ae79ae9a5 100644 --- a/docs/howtos/layers/tracks.md +++ b/docs/howtos/layers/tracks.md @@ -11,6 +11,8 @@ kernelspec: name: python3 --- +(layers-tracks)= + # Using the `tracks` layer In this document, you will learn about the `napari` `tracks` layer, including diff --git a/docs/howtos/napari_imageJ.md b/docs/howtos/napari_imageJ.md index a3d89d128..21f510fc3 100644 --- a/docs/howtos/napari_imageJ.md +++ b/docs/howtos/napari_imageJ.md @@ -1,3 +1,5 @@ +(napari-imagej)= + # napari + ImageJ how-to guide ImageJ is a Java-based image processing program that provides extensibility via Java plugins and recordable macros. It can display, edit, analyze, process, save, and print 8-bit color and grayscale, 16-bit integer, and 32-bit floating point images. It can read many image file formats, including TIFF, PNG, GIF, JPEG, BMP, DICOM, and FITS, as well as raw formats. It has a plethora of features that can be checked out [here](https://en.wikipedia.org/wiki/ImageJ#Features). diff --git a/docs/index.md b/docs/index.md index 33f5527b9..98d43b4f7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -89,7 +89,7 @@ How to install napari. ::: :::{grid-item-card} Getting started -:link: getting_started +:link: launch :link-type: ref Get started with napari. diff --git a/docs/naps/0-nap-process.md b/docs/naps/0-nap-process.md index 6bd84b80e..ba3b5a8d7 100644 --- a/docs/naps/0-nap-process.md +++ b/docs/naps/0-nap-process.md @@ -59,7 +59,7 @@ ecosystem forward, together. ### When is a NAP warranted? Most contributions to napari should go through the standard [contributing -process](napari-contributing), that is, opening a pull request to the main +process](contributing-code), that is, opening a pull request to the main repository. They will typically be uncontroversial improvements, and require little design discussion. The git commit and the pull request itself serve as an adequate record of the contribution's history. diff --git a/docs/plugins/advanced_topics/npe2_migration_guide.md b/docs/plugins/advanced_topics/npe2_migration_guide.md index b987be7da..c05f840f6 100644 --- a/docs/plugins/advanced_topics/npe2_migration_guide.md +++ b/docs/plugins/advanced_topics/npe2_migration_guide.md @@ -9,7 +9,7 @@ The primary difference between the first generation and second generation plugin system relates to how napari *discovers* plugin functionality. In the first generation plugin engine, napari had to *import* plugin modules to search for hook implementations decorated with `@napari_hook_implementation`. In `npe2`, -plugins declare their contributions *statically* with a [manifest file](../technical_references/manifest). +plugins declare their contributions *statically* with a [manifest file](plugin-manifest). ## Migrating using the `npe2` command line tool @@ -76,7 +76,7 @@ Executing `npe2 convert .` will **modify** the current directory! The `npe2 convert` command will: 1. Inspect your plugin for hook implementations, and generate an npe2-compatible - [manifest file](../technical_references/manifest), called `napari.yaml`. + [manifest file](plugin-manifest), called `napari.yaml`. 2. **Modify** your `setup.cfg` to use the new `napari.manifest` entry point, and include the manifest file in your package data. @@ -92,7 +92,7 @@ If you have any napari_plugin_engine imports or hook_implementation decorators, ``` You are encouraged to inspect the newly-generated `napari.yaml` file. Refer to -the [manifest](../technical_references/manifest) and [contributions](../technical_references/contributions) references pages +the [manifest](plugin-manifest) and [contributions](contributions-ref) references pages for details on each field in the manifest. ```{note} @@ -123,14 +123,14 @@ The next time napari is run, your plugin should be discovered as an > *This section goes into detail on the differences between first-generation and second-generation implementations. In many cases, this will be more detail than you need. If you are still struggling with a specific conversion after using -`npe2 convert` and reading the [contributions](../technical_references/contributions) reference and -[guides](../building_a_plugin/guides), this section may be of help.* +`npe2 convert` and reading the [contributions](contributions-ref) reference and +[guides](plugin-contribution-guides), this section may be of help.* Existing `napari-plugin-engine` plugins expose functionality via *hook implementations*. These are functions decorated to indicate they fullfil a *hook specification* described by napari. Though there are some exceptions, -most *hook implementations* can be straightforwardly mapped to npe2 [contributions](../technical_references/contributions) +most *hook implementations* can be straightforwardly mapped to npe2 [contributions](contributions-ref) `npe2` provides a command-line tool that will generate plugin manifests by inspecting exposed *hook implementations*. Below, we will walk through the @@ -139,7 +139,7 @@ kinds of migrations `npe2 convert` helps with. For each type of *hook specification* there is a corresponding section below with migration tips. Each lists the *hook specifications* that are relevant to that section and an example manifest. For details, refer to the -[Contributions references](../technical_references/contributions). +[Contributions references](contributions-ref). ### Readers diff --git a/docs/plugins/building_a_plugin/best_practices.md b/docs/plugins/building_a_plugin/best_practices.md index 9830179b8..fc9434965 100644 --- a/docs/plugins/building_a_plugin/best_practices.md +++ b/docs/plugins/building_a_plugin/best_practices.md @@ -211,6 +211,8 @@ make sure that you test all of the various ways that your code might be called. See [Tips for testing napari plugins](plugin-testing-tips). +(best-practices-test-coverage)= + ### How to check test coverage? The [cookiecutter diff --git a/docs/plugins/building_a_plugin/debug_plugins.md b/docs/plugins/building_a_plugin/debug_plugins.md index 96f543e6a..9e7587f46 100644 --- a/docs/plugins/building_a_plugin/debug_plugins.md +++ b/docs/plugins/building_a_plugin/debug_plugins.md @@ -87,7 +87,7 @@ To simplify the debugging process, it can be useful to isolate the execution of ## A simple plugin for following examples -To demonstrate these reloading and debugging options, we will create a small plugin called `napari-simple-reload` that prints the text entered into a box by the user. The plugin will provide an autogenerated widget, a `magic_factory` widget, and a `QWidget` - see the [contribution guides](./guides.md#widgets) for more detail. +To demonstrate these reloading and debugging options, we will create a small plugin called `napari-simple-reload` that prints the text entered into a box by the user. The plugin will provide an autogenerated widget, a `magic_factory` widget, and a `QWidget` - see the [contribution guides](widgets-contribution-guide) for more detail. Firstly, clone the code with `git clone https://github.com/seankmartin/napari-plugin-debug.git`, or download the code [here](https://github.com/seankmartin/napari-plugin-debug). Then install the package into an environment already containing napari by: @@ -199,7 +199,7 @@ Running `python reproduce_issue.py` will run our widget for the inputs `False, 0 ## Isolate the issue from napari -This solution ties in with the idea of test-driven development (see the [napari testing guidelines](../testing_and_publishing/test.md#prefer-smaller-unit-tests-when-possible)). The idea is to trust that napari will provide the information you expect it to, and test your widgets independently of the viewer. In the case above we can verify that input values work as expected like so: +This solution ties in with the idea of test-driven development (see the [napari testing guidelines](plugin-testing-prefer-unit-test)). The idea is to trust that napari will provide the information you expect it to, and test your widgets independently of the viewer. In the case above we can verify that input values work as expected like so: ```Python # test_print.py diff --git a/docs/plugins/building_a_plugin/first_plugin.md b/docs/plugins/building_a_plugin/first_plugin.md index ab34cecd3..9589c6b88 100644 --- a/docs/plugins/building_a_plugin/first_plugin.md +++ b/docs/plugins/building_a_plugin/first_plugin.md @@ -34,8 +34,8 @@ installing napari. Napari plugins are just Python packages. *Minimally*, they must: -1. Include a static [plugin manifest](../technical_references/manifest) file that details the - [contributions](../technical_references/contributions) contained in the plugin. +1. Include a static [plugin manifest](plugin-manifest) file that details the + [contributions](contributions-ref) contained in the plugin. 2. Declare a `napari.manifest` [entry point][entry_points] that allows napari to detect the plugin at runtime. @@ -178,7 +178,7 @@ autogeneration capabilities to turn this function into a widget)* ### Add a `napari.yaml` manifest -If you haven't already, create an empty [plugin manifest](../technical_references/manifest) file at `napari_hello/napari.yaml` +If you haven't already, create an empty [plugin manifest](plugin-manifest) file at `napari_hello/napari.yaml` We will use this file to tell napari: 1. That our plugin contributes a [**command**](contributions-commands) @@ -294,11 +294,11 @@ cookiecutter https://github.com/napari/cookiecutter-napari-plugin Plugins can do a lot more than just say hi! You can see the complete list of available contributions and their fields in the -[Contributions Reference](../technical_references/contributions), and learn more about each -specific contribution type in the [Guides](../building_a_plugin/guides). +[Contributions Reference](contributions-ref), and learn more about each +specific contribution type in the [Guides](plugin-contribution-guides). -Review the [Best Practices](../building_a_plugin/best_practices) when developing plugins and, -when you're ready to share your plugin, see [Testing and Publishing](../testing_and_publishing/index). +Review the [Best Practices](best-practices) when developing plugins and, +when you're ready to share your plugin, see [Testing and Publishing](plugin-test-deploy). [miniconda]: https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html [python_env]: https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-python diff --git a/docs/plugins/building_a_plugin/guides.md b/docs/plugins/building_a_plugin/guides.md index d3d48b813..e0c8f1b22 100644 --- a/docs/plugins/building_a_plugin/guides.md +++ b/docs/plugins/building_a_plugin/guides.md @@ -5,7 +5,7 @@ This page provides guides on many of the plugin contribution patterns. Each provides a general overview of the purpose of the contribution and an example implementation. For details on the type and meaning of each field in a specific contribution, See the -[contributions reference](../technical_references/contributions) +[contributions reference](contributions-ref) ```{include} ../_npe2_readers_guide.md diff --git a/docs/plugins/testing_and_publishing/test.md b/docs/plugins/testing_and_publishing/test.md index 24e366689..c73a2362b 100644 --- a/docs/plugins/testing_and_publishing/test.md +++ b/docs/plugins/testing_and_publishing/test.md @@ -10,7 +10,7 @@ Python](https://realpython.com/python-testing/) We recommend using [pytest](https://docs.pytest.org/en/6.2.x/getting-started.html) for testing your -plugin. Aim for [100% test coverage](../building_a_plugin/best_practices.md#how-to-check-test-coverage)! +plugin. Aim for [100% test coverage](best-practices-test-coverage)! ### The `make_napari_viewer_proxy` fixture @@ -32,6 +32,8 @@ def test_something_with_a_viewer(make_napari_viewer_proxy): If you embed the viewer in your own application and need to access private attributes, you can use the `make_napari_viewer` fixture. +(plugin-testing-prefer-unit-test)= + ### Prefer smaller unit tests when possible The most common issue people run into when designing tests for napari plugins is diff --git a/docs/plugins/testing_workshop_docs/1-pythons-assert-keyword.md b/docs/plugins/testing_workshop_docs/1-pythons-assert-keyword.md index 87324422b..ace9e8c5f 100644 --- a/docs/plugins/testing_workshop_docs/1-pythons-assert-keyword.md +++ b/docs/plugins/testing_workshop_docs/1-pythons-assert-keyword.md @@ -1,3 +1,5 @@ +(plugin-testing-workshop-assert)= + # 1: Python's assert keyword This tutorial defines the assert keyword in Python and shows how it can be used to write test cases for a simple function. @@ -5,10 +7,10 @@ This tutorial defines the assert keyword in Python and shows how it can be used ## Other lessons in this tutorial: * 1: This lesson (Python's assert keyword) -* 2: [Pytest testing framework](./2-pytest-testing-frameworks) -* 3: [Readers and fixtures](./3-readers-and-fixtures) -* 4: [Test coverage](./4-test-coverage) -* Resource links: [Testing resources](./testing-resources) +* 2: [Pytest testing framework](plugin-testing-workshop-pytest) +* 3: [Readers and fixtures](plugin-testing-workshop-reader-fixtures) +* 4: [Test coverage](plugin-testing-workshop-coverage) +* Resource links: [Testing resources](plugin-testing-resources) ### This lesson covers: [Assert keyword](#assert-keyword) @@ -91,4 +93,4 @@ Note that when the assertion fails, a traceback occurs. This example is a simple way to demonstrate the use of the assert keyword, but it’s not particularly useful for testing a larger codebase. This test function has to be called explicitly to test different marks. There’s not much detail when the code is running. We just get `“All passing.”` and there’s no information about other tests when one of the tests fails. -Making testing more convenient is where [testing frameworks](./2-pytest-testing-frameworks), like [pytest](https://docs.pytest.org/) come in. +Making testing more convenient is where [testing frameworks](plugin-testing-workshop-pytest), like [pytest](https://docs.pytest.org/) come in. diff --git a/docs/plugins/testing_workshop_docs/2-pytest-testing-frameworks.md b/docs/plugins/testing_workshop_docs/2-pytest-testing-frameworks.md index eab3a7e18..dbc74dc9b 100644 --- a/docs/plugins/testing_workshop_docs/2-pytest-testing-frameworks.md +++ b/docs/plugins/testing_workshop_docs/2-pytest-testing-frameworks.md @@ -1,14 +1,16 @@ +(plugin-testing-workshop-pytest)= + # 2: Pytest testing framework This lesson explains how to use the [pytest testing framework](https://docs.pytest.org/en/7.2.x/) to make testing easier. ## Other lessons in this tutorial: -* 1: [Python’s assert keyword](./1-pythons-assert-keyword.md) +* 1: [Python’s assert keyword](plugin-testing-workshop-assert) * 2: This lesson (Pytest testing framework) -* 3: [Readers and fixtures](./3-readers-and-fixtures.md) -* 4: [Test coverage](./4-test-coverage.md) -* Resource links: [Testing resources](./testing-resources.md) +* 3: [Readers and fixtures](plugin-testing-workshop-reader-fixtures) +* 4: [Test coverage](plugin-testing-workshop-coverage) +* Resource links: [Testing resources](plugin-testing-resources) ### This lesson covers: * [Testing framework features](#testing-framework-features) @@ -25,7 +27,7 @@ Testing frameworks provide a whole host of useful features, including: * Test discovery - directories can be crawled (searched) to find things that look like tests and run them * Housekeeping and ease of use - convenient methods for writing tests and cleaning up after running the tests -Pytest goes through the target destination, such as a file or directory, finding any method or function prefaced with the word `test`. It runs all the methods and functions prefaced with the word `test` but _not_ the code under the main block. When `pytest` runs against `example_test.py` (refer to the [Python's assert keyword](./1-pythons-assert-keyword.md) lesson), it finds several tests that all pass. +Pytest goes through the target destination, such as a file or directory, finding any method or function prefaced with the word `test`. It runs all the methods and functions prefaced with the word `test` but _not_ the code under the main block. When `pytest` runs against `example_test.py` (refer to the [Python's assert keyword](plugin-testing-workshop-assert) lesson), it finds several tests that all pass. If the tests fail, `pytest` is very good at tracing back the reason they failed and showing their values throughout test execution. In more complicated examples, this traceback mechanism can be very helpful. In this example, the message is that we got a `Pass` but were expecting a `Fail`. See the lines below that show the `assert` keyword and the errors. @@ -111,6 +113,6 @@ example_func_py:12: AssertionError FAILED example_func_py::test_get_grade_pass[50] - AssertionError: Expected 50 to pass, but result was Fail ``` -Another valuable feature of `pytest` is the `pytest-cov` option discussed in the [Test coverage](./4-test-coverage.md) lesson +Another valuable feature of `pytest` is the `pytest-cov` option discussed in the [Test coverage](plugin-testing-workshop-coverage) lesson -The next lesson in this tutorial on testing is the [Readers and fixtures](./3-readers-and-fixtures.md) lesson. +The next lesson in this tutorial on testing is the [Readers and fixtures](plugin-testing-workshop-reader-fixtures) lesson. diff --git a/docs/plugins/testing_workshop_docs/3-readers-and-fixtures.md b/docs/plugins/testing_workshop_docs/3-readers-and-fixtures.md index 1d82c7ef8..99ae5a03c 100644 --- a/docs/plugins/testing_workshop_docs/3-readers-and-fixtures.md +++ b/docs/plugins/testing_workshop_docs/3-readers-and-fixtures.md @@ -1,14 +1,16 @@ +(plugin-testing-workshop-reader-fixtures)= + # 3: Readers and fixtures This lesson explains how to use and test a plugin's reader function, built-in fixtures, custom fixtures, and enclosed testing. ## Other lessons in this tutorial: -* 1: [Python’s assert keyword](./1-pythons-assert-keyword.md) -* 2: [Pytest testing framework](./2-pytest-testing-frameworks.md) +* 1: [Python’s assert keyword](plugin-testing-workshop-assert) +* 2: [Pytest testing framework](plugin-testing-workshop-pytest) * 3: This lesson (Readers and fixtures) -* 4: [Test coverage](./4-test-coverage.md) -* Resource links: [Testing resources](./testing-resources.md) +* 4: [Test coverage](plugin-testing-workshop-coverage) +* Resource links: [Testing resources](plugin-testing-resources) ### This lesson covers: * [Readers](#reader) @@ -148,4 +150,4 @@ We run our tests again, and now two are collected, both passing. ## Enclosed testing Note that although we're testing a `napari` plugin, we did not need a viewer or napari to test this. It's important that we didn't need those because napari and the napari viewer are out of our control. What we can control is the code _we_ wrote. We wrote that data by simply mocking up an array and getting a temporary path to it. We could thoroughly test our functions in an enclosed way without relying on other people's code or mocking up many complicated objects. -The next lesson in this series on testing is [Test coverage](./4-test-coverage). +The next lesson in this series on testing is [Test coverage](plugin-testing-workshop-coverage). diff --git a/docs/plugins/testing_workshop_docs/4-test-coverage.md b/docs/plugins/testing_workshop_docs/4-test-coverage.md index 737f02a1a..dc0b9839d 100644 --- a/docs/plugins/testing_workshop_docs/4-test-coverage.md +++ b/docs/plugins/testing_workshop_docs/4-test-coverage.md @@ -1,12 +1,14 @@ +(plugin-testing-workshop-coverage)= + # 4: Test coverage ## Other lessons in this tutorial: -* 1: [Python’s assert keyword](./1-pythons-assert-keyword.md) -* 2: [Pytest testing framework](./2-pytest-testing-frameworks.md) -* 3: [Readers and fixtures](./3-readers-and-fixtures.md) +* 1: [Python’s assert keyword](plugin-testing-workshop-assert) +* 2: [Pytest testing framework](plugin-testing-workshop-pytest) +* 3: [Readers and fixtures](plugin-testing-workshop-reader-fixtures) * 4: This lesson (Test coverage) -* Resource links: [testing resources](./testing-resources.md) +* Resource links: [testing resources](plugin-testing-resources) ### This lesson covers: * [Coverage](#coverage) diff --git a/docs/plugins/testing_workshop_docs/index.md b/docs/plugins/testing_workshop_docs/index.md index a4e968d7d..06535c5d3 100644 --- a/docs/plugins/testing_workshop_docs/index.md +++ b/docs/plugins/testing_workshop_docs/index.md @@ -2,8 +2,8 @@ # In-depth guide to plugin testing This is the frontpage for the tutorial developed from the [January 2022 workshop on testing](https://youtu.be/IsHYnI8Tbfw?list=PLilvrWT8aLuYID3YZ7KddS5ky2SaH4DKK). This tutorial will be more meaningful to you if you are familiar with the Python programming language and napari software. These lessons summarize the information in the video and should stand on their own. The lessons are listed here with the timings on the video next to each: -* 1: [Python’s assert keyword](./1-pythons-assert-keyword.md) - starts at minute [5:23](https://youtu.be/IsHYnI8Tbfw?list=PLilvrWT8aLuYID3YZ7KddS5ky2SaH4DKK&t=333). -* 2: [Pytest testing framework](./2-pytest-testing-frameworks.md) - starts at minute [9:21](https://youtu.be/IsHYnI8Tbfw?list=PLilvrWT8aLuYID3YZ7KddS5ky2SaH4DKK&t=561). -* 3: [Readers and fixtures](./3-readers-and-fixtures.md) - starts at minute [15:42](https://youtu.be/IsHYnI8Tbfw?list=PLilvrWT8aLuYID3YZ7KddS5ky2SaH4DKK&t=942). -* 4: [Test coverage](./4-test-coverage.md) - starts at minute [28:26](https://youtu.be/IsHYnI8Tbfw?list=PLilvrWT8aLuYID3YZ7KddS5ky2SaH4DKK&t=1706). -* Resource links: [Testing resources](./testing-resources.md) \ No newline at end of file +* 1: [Python’s assert keyword](plugin-testing-workshop-assert) - starts at minute [5:23](https://youtu.be/IsHYnI8Tbfw?list=PLilvrWT8aLuYID3YZ7KddS5ky2SaH4DKK&t=333). +* 2: [Pytest testing framework](plugin-testing-workshop-pytests) - starts at minute [9:21](https://youtu.be/IsHYnI8Tbfw?list=PLilvrWT8aLuYID3YZ7KddS5ky2SaH4DKK&t=561). +* 3: [Readers and fixtures](plugin-testing-workshop-reader-fixtures) - starts at minute [15:42](https://youtu.be/IsHYnI8Tbfw?list=PLilvrWT8aLuYID3YZ7KddS5ky2SaH4DKK&t=942). +* 4: [Test coverage](plugin-testing-workshop-coverage) - starts at minute [28:26](https://youtu.be/IsHYnI8Tbfw?list=PLilvrWT8aLuYID3YZ7KddS5ky2SaH4DKK&t=1706). +* Resource links: [Testing resources](plugin-testing-resources) \ No newline at end of file diff --git a/docs/plugins/testing_workshop_docs/testing-resources.md b/docs/plugins/testing_workshop_docs/testing-resources.md index 4c0ed5fef..c3f0301f6 100644 --- a/docs/plugins/testing_workshop_docs/testing-resources.md +++ b/docs/plugins/testing_workshop_docs/testing-resources.md @@ -1,3 +1,5 @@ +(plugin-testing-resources)= + # Testing resources These resources may be helpful in developing tests: diff --git a/docs/roadmaps/0_3.md b/docs/roadmaps/0_3.md index d6b18c36e..1bbe9a750 100644 --- a/docs/roadmaps/0_3.md +++ b/docs/roadmaps/0_3.md @@ -72,6 +72,6 @@ This document is meant to be a snapshot of tasks and features that the `napari` This roadmap is also designed to be in accordance with our stated [mission](our-mission) to be the **multi-dimensional image viewer for Python** and to **provide graphical user interface (GUI) access to a plugin ecosystem of image analysis tools for scientists** to use in their daily work. -For more details on the high level goals and decision making processes within napari you are encouraged to read our [mission and values statement](mission-and-values) and look at our [governance model](napari-governance). If you are interested in contributing to napari, we'd love to have your contributions, and you should read our [contributing guidelines](napari-contributing) for information on how to get started. +For more details on the high level goals and decision making processes within napari you are encouraged to read our [mission and values statement](mission-and-values) and look at our [governance model](napari-governance). If you are interested in contributing to napari, we'd love to have your contributions, and you should read our [contributing guidelines](contributing-code) for information on how to get started. Another good place to look for information around bigger-picture discussions within napari are our issues tagged with the [`long-term feature` label](https://github.com/napari/napari/labels/long-term%20feature). diff --git a/docs/roadmaps/0_3_retrospective.md b/docs/roadmaps/0_3_retrospective.md index 1bd750821..9ce80c227 100644 --- a/docs/roadmaps/0_3_retrospective.md +++ b/docs/roadmaps/0_3_retrospective.md @@ -112,6 +112,6 @@ This document is meant to be a snapshot of tasks and features that the `napari` This roadmap is also designed to be in accordance with our stated [mission](our-mission) to be the **multi-dimensional image viewer for Python** and to **provide graphical user interface (GUI) access to a plugin ecosystem of image analysis tools for scientists** to use in their daily work. -For more details on the high level goals and decision making processes within napari you are encouraged to read our [mission and values statement](mission-and-values) and look at our [governance model](napari-governance). If you are interested in contributing to napari, we'd love to have your contributions, and you should read our [contributing guidelines](napari-contributing) for information on how to get started. +For more details on the high level goals and decision making processes within napari you are encouraged to read our [mission and values statement](mission-and-values) and look at our [governance model](napari-governance). If you are interested in contributing to napari, we'd love to have your contributions, and you should read our [contributing guidelines](contributing-code) for information on how to get started. Another good place to look for information around bigger-picture discussions within napari are our issues tagged with the [`long-term feature` label](https://github.com/napari/napari/labels/long-term%20feature). diff --git a/docs/roadmaps/0_4.md b/docs/roadmaps/0_4.md index 0639bf66f..8e5df6a97 100644 --- a/docs/roadmaps/0_4.md +++ b/docs/roadmaps/0_4.md @@ -46,7 +46,7 @@ goal in mind, and specifically by tackling the following: releases, we aim to bring this functionality out of experimental status, as well as extend it to other layer types and multiscale 3D data. -- **Improving the performance of operations on in-memory data**. Even when data is loaded in memory, some operations, such as label and shape painting or slicing along large numbers of points can be slow. We will continue developing our [benchmark suite](../developers/benchmarks.md) and work to integrate it into our development process. See the [`performance` label](https://github.com/napari/napari/labels/performance) for a current list of issues related to performance. +- **Improving the performance of operations on in-memory data**. Even when data is loaded in memory, some operations, such as label and shape painting or slicing along large numbers of points can be slow. We will continue developing our [benchmark suite](benchmarks) and work to integrate it into our development process. See the [`performance` label](https://github.com/napari/napari/labels/performance) for a current list of issues related to performance. - Add **physical coordinates**. We now have a world coordinate system and transforms that can move between data coordinates, world coordinates, and the canvas where things are rendered; however, we still don't have a concept of phyiscal units. See [#1701](https://github.com/napari/napari/issues/1701) for additional discussion. @@ -129,6 +129,6 @@ This document is meant to be a snapshot of tasks and features that the `napari` This roadmap is also designed to be in accordance with our stated [mission](our-mission) to be the **multi-dimensional image viewer for Python** and to **provide graphical user interface (GUI) access to a plugin ecosystem of image analysis tools for scientists** to use in their daily work. -For more details on the high level goals and decision making processes within napari you are encouraged to read our [mission and values statement](mission-and-values) and look at our [governance model](napari-governance). If you are interested in contributing to napari, we'd love to have your contributions, and you should read our [contributing guidelines](napari-contributing) for information on how to get started. +For more details on the high level goals and decision making processes within napari you are encouraged to read our [mission and values statement](mission-and-values) and look at our [governance model](napari-governance). If you are interested in contributing to napari, we'd love to have your contributions, and you should read our [contributing guidelines](contributing-code) for information on how to get started. Another good place to look for information around bigger-picture discussions within napari are our issues tagged with the [`long-term feature` label](https://github.com/napari/napari/labels/long-term%20feature). diff --git a/docs/roadmaps/index.md b/docs/roadmaps/index.md index 520ba90fa..c17a98251 100644 --- a/docs/roadmaps/index.md +++ b/docs/roadmaps/index.md @@ -1,3 +1,5 @@ +(roadmaps)= + # Roadmaps The current `napari` roadmap can be seen in the following GitHub board: [napari global roadmap](https://github.com/orgs/napari/projects/24/views/2?pane=info) diff --git a/docs/tutorials/annotation/annotate_points.md b/docs/tutorials/annotation/annotate_points.md index f2205ed34..d271990d7 100644 --- a/docs/tutorials/annotation/annotate_points.md +++ b/docs/tutorials/annotation/annotate_points.md @@ -1,3 +1,5 @@ +(annotating-points)= + # Annotating videos with napari **Note**: this tutorial has been updated and is now compatible with napari > 0.4.5 and magicgui > 0.2.5. For details, see [this pull request](https://github.com/napari/napari.github.io/pull/114). @@ -182,7 +184,7 @@ def point_annotator( First, we load the movie to be annotated. Since behavior movies can be quite long, we will use a lazy loading strategy (i.e., we will only load the frames as they are used). Using [`dask-image`](https://github.com/dask/dask-image), we can construct an object that we can pass to napari for lazy loading in just one line. -For more explanation on using dask to lazily load images in napari, see [this](../processing/dask) tutorial. +For more explanation on using dask to lazily load images in napari, see [this](dask) tutorial. ```python stack = imread(im_path) diff --git a/docs/tutorials/fundamentals/getting_started.md b/docs/tutorials/fundamentals/getting_started.md index c16c81ae7..09911576e 100644 --- a/docs/tutorials/fundamentals/getting_started.md +++ b/docs/tutorials/fundamentals/getting_started.md @@ -1,8 +1,8 @@ -(getting_started)= -# How to launch `napari` +(launch)= +# How to launch napari -This tutorial assumes you have already installed `napari`. -For help with installation see our [installation tutorial](./installation). +This tutorial assumes you have already installed napari. +For help with installation see our [installation tutorial](installation). This tutorial will teach you all the different ways to launch `napari`. At the end of the tutorial you should be able to launch `napari` and see the viewer your favorite way. @@ -170,7 +170,7 @@ and where data changed in the GUI will be accessible in the notebook. To learn more about: -* how to use the `napari` viewer graphical user interface (GUI), - checkout the [viewer tutorial](./viewer) -* how to use the `napari` viewer with different types of `napari` layers, see - [layers at a glance](../../guides/layers) +* how to use the napari viewer graphical user interface (GUI), + checkout the [viewer tutorial](viewer-tutorial) +* how to use the napari viewer with different types of napari layers, see + [layers at a glance](layers-glance) diff --git a/docs/tutorials/fundamentals/installation.md b/docs/tutorials/fundamentals/installation.md index 14ed2f13d..8dcda2f3e 100644 --- a/docs/tutorials/fundamentals/installation.md +++ b/docs/tutorials/fundamentals/installation.md @@ -25,6 +25,8 @@ This guide will teach you how to do a clean install of **napari** and launch the If you want to contribute code back into napari, you should follow the [development installation instructions in the contributing guide](https://napari.org/developers/contributing.html) instead. ``` +(install-python-package)= + ## Install as Python package (recommended) This installation method allows you to use napari from Python to programmatically @@ -238,7 +240,7 @@ extended with napari plugins installed directly via the app. ```{important} Note that the bundled app is still in active development, and may not be very stable. We strongly recommend -[installing as a Python package instead](#install-as-python-package-recommended). +[installing as a Python package instead](install-python-package). ``` To access the cross platform bundles you can visit our [release @@ -253,11 +255,10 @@ expand the `Assets` section. You can then download the appropriate file for your ## Next steps -- to start learning how to use napari, checkout our [getting -started](./getting_started) tutorial +- to start learning how to use napari, checkout our [getting started](launch) tutorial - if you are interested in contributing to napari please check our [contributing -guidelines](../../developers/contributing.md) +guidelines](contributing-code) - if you are running into issues or bugs, please open a [new issue](https://github.com/napari/napari/issues/new/choose) on our [issue tracker](https://github.com/napari/napari/issues) - if you want help using napari, we are a community partner on the [imagesc diff --git a/docs/tutorials/fundamentals/quick_start.md b/docs/tutorials/fundamentals/quick_start.md index efb30d7c1..e01e58049 100644 --- a/docs/tutorials/fundamentals/quick_start.md +++ b/docs/tutorials/fundamentals/quick_start.md @@ -22,7 +22,7 @@ napari is a fast, interactive, multi-dimensional image viewer, with [a vibrant p napari is an open source project on [GitHub](https://github.com/napari/napari) to facilitate transparency, reuse, and extensibility. -At its core, it provides critical viewer features out-of-the-box, such as support for [large multi-dimensional data](../processing/dask); [“layers”](..//start_index) to simultaneously visualize images, models, and analysis results; and easy manual, interactive annotation in 3D. +At its core, it provides critical viewer features out-of-the-box, such as support for [large multi-dimensional data](dask); [“layers”](layers-glance) to simultaneously visualize images, models, and analysis results; and easy manual, interactive annotation in 3D. This tutorial uses napari 0.4.14.
@@ -40,7 +40,7 @@ This tutorial is for napari first-timers to give them a quick glance of what nap - Get the cell area measurement - Next steps -Along the way, you will see how to access napari functions from [Python code](../../api/index) and from GUI - though for different purposes, one method might be easier than another. This quick start guide will not cover ALL possible methods but only some ways to perform basic tasks. For the more complete guide, please visit [our usage guide](../../usage.md). +Along the way, you will see how to access napari functions from [Python code](api) and from GUI - though for different purposes, one method might be easier than another. This quick start guide will not cover ALL possible methods but only some ways to perform basic tasks. For the more complete guide, please visit [our usage guide](usage). You will also see some examples of plugins. The core napari viewer focuses on domain-agnostic functions such as layer controls. Analyses and domain specific functions, such as reading a special file format and image segmentation, live in the realm of [plugins](https://www.napari-hub.org/). @@ -70,13 +70,13 @@ You will also see some examples of plugins. The core napari viewer focuses on do ``` -If you run into any issues, please visit the more detailed [installation guide](./installation), or [report an issue on GitHub](https://github.com/napari/napari/issues/new/choose)! +If you run into any issues, please visit the more detailed [installation guide](installation), or [report an issue on GitHub](https://github.com/napari/napari/issues/new/choose)! +++ ### Open napari -napari can be opened in one of [multiple ways](./getting_started), depending on how it's used in your image analysis workflow. +napari can be opened in one of [multiple ways](launch), depending on how it's used in your image analysis workflow. Here we will be mainly focused on the GUI application. @@ -135,7 +135,7 @@ nbscreenshot(viewer, alt_text="image of a single cell opened in napari viewer") The layer controls panel at the upper left of the viewer allows you to adjust contrast, colormap, and other layer properties. These settings affect the visualization, but do not affect the underlying data. -To change the image display through the [API](../../api/index), in IPython console, type +To change the image display through the [API](api), in IPython console, type ```python viewer.layers['cell'].colormap = "yellow" @@ -199,6 +199,6 @@ viewer.close_all() - If you don't see the functions you need in existing plugins, try to make your own widget with [magicgui](https://napari.org/magicgui/). -- If you've developed some functionality that you think would benefit the community as a whole, consider publishing it as a [plugin](../../plugins/index)! +- If you've developed some functionality that you think would benefit the community as a whole, consider publishing it as a [plugin](plugins-index)! -- Help the napari project by [filing issues](https://github.com/napari/napari/issues) for bugs you encounter or features that you'd like to see! Or even better, come [join the community meetings](../../community/meeting_schedule) and get to know the team. +- Help the napari project by [filing issues](https://github.com/napari/napari/issues) for bugs you encounter or features that you'd like to see! Or even better, come [join the community meetings](meeting-schedule) and get to know the team. diff --git a/docs/tutorials/fundamentals/viewer.md b/docs/tutorials/fundamentals/viewer.md index 74b9e3f49..5010d17f5 100644 --- a/docs/tutorials/fundamentals/viewer.md +++ b/docs/tutorials/fundamentals/viewer.md @@ -18,7 +18,7 @@ kernelspec: Welcome to the tutorial on the **napari** viewer! -This tutorial assumes you have already installed **napari** and know how to launch the viewer. For help with installation see our [installation](./installation) tutorial. For help launching the viewer see our [getting started](./getting_started) tutorial. +This tutorial assumes you have already installed **napari** and know how to launch the viewer. For help with installation see our [installation](installation) tutorial. For help launching the viewer see our [getting started](launch) tutorial. This tutorial will teach you about the **napari** viewer, including how to use its graphical user interface (GUI) and how the data within it is organized. At the end of the tutorial, you should understand both the layout of the viewer on the screen and the data inside of it. @@ -26,7 +26,7 @@ This tutorial will teach you about the **napari** viewer, including how to use i ## Launching the viewer -As discussed in the [getting started](./getting_started) tutorial, the napari viewer can be launched from the command-line, a python script, an IPython console, or a Jupyter notebook. All four methods launch the same viewer, and anything related to interacting with the viewer on the screen applies equally to all of them. We will use the syntax for running the code inside a jupyter notebook with each code block below pasted into its own cell, but if you'd like to use a python script instead, simply copy and paste the code blocks into scripts with [`napari.run()`](https://napari.org/stable/api/napari.html#napari.run) as the final line (this starts an event loop which will +As discussed in the [getting started](launch) tutorial, the napari viewer can be launched from the command-line, a python script, an IPython console, or a Jupyter notebook. All four methods launch the same viewer, and anything related to interacting with the viewer on the screen applies equally to all of them. We will use the syntax for running the code inside a jupyter notebook with each code block below pasted into its own cell, but if you'd like to use a python script instead, simply copy and paste the code blocks into scripts with [`napari.run()`](https://napari.org/stable/api/napari.html#napari.run) as the final line (this starts an event loop which will open an interactive viewer) and run them. **Note:** There is also an IPython console available in napari, when napari is launched from the terminal, from a Python script, or when you use the napari bundled app. You can open it with the IPython console button (far left viewer button) or with the menu option **Window** > **console**. You can use this console to programmatically interact with an open viewer using the API methods illustrated in this tutorial. @@ -76,7 +76,7 @@ nbscreenshot(viewer, alt_text="photograph of an astronaut in napari viewer") viewer.close() ``` - {func}`imshow` and the {meth}`add_image` methods accept any numpy-array like object as input, including n-dimensional arrays. For more information on adding images to the viewer see the [image layer guide](../../howtos/layers/image). + {func}`imshow` and the {meth}`add_image` methods accept any numpy-array like object as input, including n-dimensional arrays. For more information on adding images to the viewer see the [image layer guide](image-layer). Now we will continue exploring the rest of the viewer. @@ -135,8 +135,7 @@ The **canvas** is in the center of the viewer and contains the visual display of +++ - -(layer_list)= +(layer-list)= ### Layer list Layers are one of the basic napari objects. There are different layer types for `Image`, `Points`, `Shapes`, and other data types. They can be added to the viewer either programmatically or through the GUI. Once added, they populate the layer list located on the bottom left side of the canvas. @@ -510,7 +509,7 @@ viewer.theme = 'dark' You can also change the theme using the "Toggle theme" keyboard shortcut, by default `Command/Control+Shift+T`. Note that changing the theme using this shortcut will only change the *current* viewer theme. If you wish to make the change permanent for all viewers, make sure to also change your settings in the **Appearance** tab of the **Preferences** menu. -Adding your own custom theme isn't too hard but it requires creating your own color `palette` and rebuilding the icons. It's also possible for [plugins to contribute a theme](contributions-themes). If people want more themes, we're happy to add them or you can look at our [contributing guidelines](../../developers/contributing) for more information about building the icons and add one yourself! +Adding your own custom theme isn't too hard but it requires creating your own color `palette` and rebuilding the icons. It's also possible for [plugins to contribute a theme](contributions-themes). If people want more themes, we're happy to add them or you can look at our [contributing guidelines](contributing-code) for more information about building the icons and add one yourself! +++ @@ -568,7 +567,7 @@ The ability to add custom keybindings dramatically increases what is possible wi ## Next steps -This tutorial has given you an overview of the functionality available on the **napari** viewer, including the {class}`LayerList` and some of the different layer types. To learn more about the different layer types **napari** supports, check out [our guides on using layers](../../howtos/layers/index). +This tutorial has given you an overview of the functionality available on the **napari** viewer, including the {class}`LayerList` and some of the different layer types. To learn more about the different layer types **napari** supports, check out [our guides on using layers](using-layers). For a more detailed introduction to layer manipulation see -[Layers at a glance](../../guides/layers). +[Layers at a glance](layers-glance). diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 0ef3b8246..888fd2af5 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -1,9 +1,9 @@ -(napari-tutorials)= +(tutorials)= # napari tutorials These tutorials will help you explore the main usage modes and methods of napari, and target people who want to use napari. If you are also interested -in contributing to napari then please check out [the Community page](../community/index). +in contributing to napari then please check out [the Community page](community). ::::{grid} :::{grid-item-card} Annotation @@ -44,4 +44,4 @@ As you make your way through the tutorials, if you spot any errors or areas that can be improved, please raise an issue on the repository or make a pull request! We love it when our community helps make them better for everyone! To see how to modify documentation pages, please see our -[documentation contributing guide](../developers/documentation/index). \ No newline at end of file +[documentation contributing guide](contributing-docs). \ No newline at end of file diff --git a/docs/tutorials/processing/dask.md b/docs/tutorials/processing/dask.md index b7616daa5..f01310849 100644 --- a/docs/tutorials/processing/dask.md +++ b/docs/tutorials/processing/dask.md @@ -1,3 +1,5 @@ +(dask)= + # Using Dask and napari to process & view large datasets Often in microscopy, multidimensional data is acquired and written to disk in many small files, diff --git a/docs/tutorials/segmentation/index.md b/docs/tutorials/segmentation/index.md index 23d5a5af6..eef2844d1 100644 --- a/docs/tutorials/segmentation/index.md +++ b/docs/tutorials/segmentation/index.md @@ -1,6 +1,6 @@ (segmentation)= # Segmentation -This section contains tutorials for segmentation [labeling](../../howtos/layers/labels). +This section contains tutorials for segmentation [labeling](layers-labels). * [Annotating segmentation with text and bounding boxes](annotate_segmentation) diff --git a/docs/tutorials/start_index.md b/docs/tutorials/start_index.md index b8113d8dc..ee0c8d317 100644 --- a/docs/tutorials/start_index.md +++ b/docs/tutorials/start_index.md @@ -1,8 +1,10 @@ - # Getting started +(getting-started)= + +# Getting started The following documents will give you an overview of how to install and use -napari. For more detailed use-cases, check out the [napari tutorials](./index) -or [How-to guides](../howtos/index). +napari. For more detailed use-cases, check out the [napari tutorials](tutorials) +or [How-to guides](how-tos). ::::{grid} :::{grid-item-card} Quick start @@ -22,7 +24,7 @@ How to do a clean install of napari and launch the viewer. ::: :::{grid-item-card} How to launch napari -:link: getting_started +:link: launch :link-type: ref This tutorial will teach you all the different ways to launch napari. diff --git a/docs/tutorials/tracking/cell_tracking.md b/docs/tutorials/tracking/cell_tracking.md index 497c83e4d..079cfcc71 100644 --- a/docs/tutorials/tracking/cell_tracking.md +++ b/docs/tutorials/tracking/cell_tracking.md @@ -1,6 +1,6 @@ # Single cell tracking with napari -In this application note, we will use napari (requires version 0.4.0 or greater) to visualize single cell tracking data using the `Tracks` layer. For an overview of the `Tracks` layer, please see the [tracks layer guide](../../howtos/layers/tracks). +In this application note, we will use napari (requires version 0.4.0 or greater) to visualize single cell tracking data using the `Tracks` layer. For an overview of the `Tracks` layer, please see the [tracks layer guide](layers-tracks). This application note covers two examples: 1. Visualization of a cell tracking challenge dataset @@ -48,7 +48,7 @@ def load_image(idx: int): stack = np.asarray([load_image(i) for i in range(NUM_IMAGES)]) ``` -For each image in the time-lapse sequence, we will now extract the unique track label (`track_id`), centroid and timestamp in order to create the track data we will pass to the `Tracks` layer. For more information on the format of the track data, please see the "tracks data" section of the [tracks layer guide](../../howtos/layers/tracks). +For each image in the time-lapse sequence, we will now extract the unique track label (`track_id`), centroid and timestamp in order to create the track data we will pass to the `Tracks` layer. For more information on the format of the track data, please see the "tracks data" section of the [tracks layer guide](layers-tracks). ```python def regionprops_plus_time(idx): @@ -92,7 +92,7 @@ napari.run() ### Calculating the graph using the lineage information The `Tracks` layer can also be used to visualize a track 'graph' using the additional keyword argument `graph`. The `graph` represents associations between tracks, by defining the -mapping between a `track_id` and the parents of the track. This graph can be useful in single cell tracking to understand the lineage of cells over multiple cell division events. For more information on the format of the track `graph`, please see the "tracks graph" section of the [tracks layer guide](../../howtos/layers/tracks). +mapping between a `track_id` and the parents of the track. This graph can be useful in single cell tracking to understand the lineage of cells over multiple cell division events. For more information on the format of the track `graph`, please see the "tracks graph" section of the [tracks layer guide](layers-tracks). In the cell tracking challenge dataset, cell lineage information is stored in a text file `man_track.txt` in the following format: diff --git a/docs/usage.md b/docs/usage.md index 42bebd5a7..3a546258c 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,3 +1,5 @@ +(usage)= + # Usage napari leverages the power of Python to enable fast and interactive browsing,