Update docs (#1192)

* Bump copyright year to 2026 and cleanup

Update copyright headers across the codebase from 2025 to 2026. Also apply a set of small, mainly non-functional cleanups: reformat long lines and comprehensions, normalize dict/list formatting, add missing trailing commas, tidy imports and string quoting in menus, and minor expression simplifications (e.g. tiling overlay). Several test package __init__.py files were added and many tests were updated accordingly. No major logic changes intended.

* Update acquiring data docs and add images

Rename beginner.rst to acquiring_data.rst and refactor the acquiring-data guide: simplify environment/launch instructions, add guidance for Virtual Devices (synthetic hardware), update image paths, and clarify stage control wording. Add multiple UI screenshots to docs/source/images (MainApp, Camera/Channels/Stage tabs, channel selector images, configurator, etc.). Also add the "mss" package to pyproject.toml dependencies used for the docs.

* Revise docs structure and add capture GUI tool

Reorganize and expand the documentation and tooling for the getting-started flow and documentation screenshots. Add docs/AGENTS.md with authoring guidelines and expectations for contributors and automated agents. Replace the old docs/capture_gui.py with an executable, CLI-driven capture tool (manifest/grouping, settle/delay options, configurator support, robust context build/teardown, and reusable capture specs) that writes screenshots to docs/source/images. Restructure Getting Started content: remove the old quick_start page and legacy software_installation, add new pages for minimum system requirements, software installation (strategies: Conda/venv/uv/GitHub), launching navigate, and configuring navigate; also move and edit the power management page into the getting-started section. Remove obsolete images and update references in software_configuration.rst accordingly. These changes improve doc organization, clarity for new users, and reproducible screenshot capture for docs maintenance.

* Capture combobox dropdowns; add sensor/ROI docs

Improve screenshot capture and refresh docs. Make settle_window ensure the Tk root is visible/topmost before capturing. Add _capture_combobox_dropdown helper and refactor existing combobox capture to use it; add new capture runners for sensor-mode and ROI-definition and register them in CAPTURES. Update getting-started RST to center-align images, fix image paths, and add new sensor-mode.png and ROI-definition.png (and refresh several other doc screenshots). These changes make dropdown screenshots more reliable and update the documentation visuals.

* Refactor docs images and capture GUI

Move and consolidate documentation screenshots, update rst references, and enhance the GUI capture tooling. AGENTS.md gains a "Hardware Docs Conventions" section; many beginner images were removed from their old folder and added under docs/source/images with updated paths in acquiring_data.rst. capture_gui.py was extended with helpers to prepare windows for screenshots (suppress hover tooltips, settle geometry), robust combobox/popdown handling, mode/state helpers, many new capture routines for acquiring-data screenshots, and new entries added to the CAPTURES list. Also small textual edits in camera.rst and a change to pyproject.toml.

* docs: reflow and clarify file_formats.rst

Reflow and clean up the Supported File Formats docs for readability and consistency. Added a section anchor and a File Types subsection, normalized RST directives (note::), and introduced subsection adornments (~) for TIFF/BigDataViewer/OME-Zarr blocks. Minor copy edits: reworded timing line to "Median write time reported in milliseconds", updated the OME-Zarr link text to OME-NGFF 0.4, and fixed hard drive size formatting ("7680 GB"). These changes are purely documentation/formatting to improve clarity.

* Restructure docs: contributing & hardware

Reorganize documentation layout to separate contributor and user content. Move advanced hardware/how-to pages into a new 'Hardware Integration' section under contributing; add hardware_communication_guidelines, hardware_integration index, code_of_conduct, and code_quality pages; replace legacy intermediate how-to with a new Smart Acquisition Routines guide; update contributing guidelines to reference the new pages and streamline contribution workflow; add developer_install anchor and update docs index to include the new entries. Removed obsolete 03_i_want_to index files and relocated add_new_device/advanced files to the contributing hardware path.

* Add feature GUI captures and reorganize docs images

Add numerous capture helper functions to docs/capture_gui.py for feature-list and multiposition examples and register corresponding CaptureSpec entries. Rework docs/source/01_getting_started/07_smart_routines.rst to use the new image locations and clarify the walkthrough text. Update docs/source/conf.py to enable the todo extension (disabled by default). Remove legacy images from docs/source/01_getting_started/... and add consolidated images and several debug screenshots under docs/source/images/.

* Add UI walkthrough docs and camera menu

Add a multi-page User Interface Walkthrough (split into six new rst pages and images) and update the main walkthrough to a toctree. Register the new "Camera Offset and Variance Maps" menu entry in menus.py (and remove a redundant add_command). Add daheng camera to autodoc_mock_imports so docs build, and add smart_microscope_mode: True to the example experiment.yml. Also adjust a camera-settings unit test to safely read exposure_time with a fallback default.

* Remove photometrics dependency from pyproject

Remove duplicate project.optional-depenencies entry for photometrics...

* Fix tests.

MultiPositions in the experiment.yml file is now obsolete.
Accidentally appended smart_microscope_mode when discussing code, and forgot to remove it. Likewise, same happened with the test_camera_settings file...

* Add UI screenshot capture tooling and images

Extend docs capture tooling and update user guide images: capture_gui.py gains many helper functions for popup/notebook captures, new per-frame capture routines, and numerous CaptureSpec entries to generate UI screenshots. Add a large set of new UI images (docs/source/images/*), remove obsolete debug images, and update multiple RST pages to reference the new screenshots. Also add a developer concepts doc and small project metadata/index tweaks to include the new assets.

* Add GUI capture functions, docs and images

Add screenshot capture handlers to docs/capture_gui.py (histogram/intensity/metrics/render/MIP/waveform frames and preview population), including numpy/math usage and new CaptureSpec entries for automated doc screenshots. Add corresponding UI images and update multiple RST docs to reference new frames and improve configuration/setup/help text. Fix WaveformPopupController to create the advanced popup with a Tk-backed parent (self.view.popup) and add a regression test ensuring the popup master is the proper widget.

* Update README, hardware docs, and template loop

Revamp project README with new header, badges, documentation links, OS note, consolidated install instructions (pip install navigate-micro), first-launch steps, developer source install, CLI argument reference, and issue link. Rename and rework hardware integration docs to "Adding New Hardware", clarify scope and add a toctree for subpages. Adjust Sphinx template in custom_module.rst to render module basenames (use item.split('.')[-1]) when listing modules.

* Make waveform_popup tests more robust

Harden waveform_popup unit tests by handling optional attributes and avoiding leaks between tests. Add a _MISSING sentinel and capture original camera_setting_controller and model via getattr, then mock them inside a try/finally and restore or delete them as appropriate. Preserve the real view widget.set (mocking only the setter) to avoid replacing the whole view and leaking a mocked Tk parent. Also update galvo name strings and assertions accordingly. These changes prevent test interference and improve reliability.

Author: kevin-m-dean

README.md

@@ -1,58 +1,99 @@
 <h1 align="center">
-<img src="https://github.com/TheDeanLab/navigate/blob/develop/src/navigate/view/icon/mic.ico?raw=true" />
-
-navigate
-<h2 align="center">
-	open source light sheet microscope control
-</h2>
+  <img src="https://github.com/TheDeanLab/navigate/blob/develop/src/navigate/view/icon/mic.ico?raw=true" alt="navigate icon" />
+  <br />
+  navigate
 </h1>
 
+<p align="center"><strong>open source light-sheet microscope control</strong></p>
 
+[![Published in Nature Methods](https://img.shields.io/badge/Published%20in-Nature%20Methods-blue)](https://doi.org/10.1038/s41592-024-02413-4)
+[![GitHub Stars](https://img.shields.io/github/stars/TheDeanLab/navigate?style=social)](https://github.com/TheDeanLab/navigate)
+[![PyPI Version](https://img.shields.io/pypi/v/navigate-micro)](https://pypi.org/project/navigate-micro/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/navigate-micro)](https://pypi.org/project/navigate-micro/)
+[![Docs](https://github.com/TheDeanLab/navigate/actions/workflows/build_docs.yaml/badge.svg)](https://github.com/TheDeanLab/navigate/actions/workflows/build_docs.yaml)
 [![Tests](https://github.com/TheDeanLab/navigate/actions/workflows/push_checks.yaml/badge.svg)](https://github.com/TheDeanLab/navigate/actions/workflows/push_checks.yaml)
 [![codecov](https://codecov.io/gh/TheDeanLab/navigate/branch/develop/graph/badge.svg?token=270RFSZGG5)](https://codecov.io/gh/TheDeanLab/navigate)
 
-**navigate** is an open source Python package for control of light-sheet microscopes.
-It allows for easily reconfigurable hardware setups and automated acquisition routines.
+**navigate** is an open-source Python package for light-sheet microscope control. It supports reconfigurable hardware setups and automated acquisition routines.
 
-### Quick install
+> **OS compatibility:** **navigate** is primarily used on Windows for microscope operation because many hardware drivers are Windows-focused. Linux and macOS are useful for development and limited testing.
 
-Download and install [Miniconda](https://docs.conda.io/en/latest/miniconda.html#latest-miniconda-installer-links).
+## Documentation
 
-```
+Project documentation is published at: <https://thedeanlab.github.io/navigate/>
+
+Key entry points:
+- Getting Started: <https://thedeanlab.github.io/navigate/01_getting_started/03_software_installation.html>
+- Configure navigate: <https://thedeanlab.github.io/navigate/01_getting_started/05_configuring_navigate.html>
+- Developer Install: <https://thedeanlab.github.io/navigate/03_contributing/02_developer_install/02_developer_install.html>
+- Contributing Guidelines: <https://thedeanlab.github.io/navigate/03_contributing/01_contributing_guidelines/01_contributing_guidelines.html>
+
+## Quick Install (Conda + PyPI)
+
+Install Miniconda: <https://docs.conda.io/en/latest/miniconda.html>
+
+```bash
 conda create -n navigate python=3.9.7
 conda activate navigate
-pip install git+https://github.com/TheDeanLab/navigate.git
+pip install navigate-micro
+```
+
+## First Launch (Recommended)
+
+```bash
+# 1) Validate in synthetic hardware mode
+navigate -sh
+
+# 2) Open the configurator to create/edit configuration files
+navigate -c
+
+# 3) Launch normally
+navigate
+```
+
+## Install From Source (Developers)
+
+```bash
+git clone https://github.com/TheDeanLab/navigate.git
+cd navigate
+```
+
+Install in editable mode with development dependencies:
+
+```bash
+# Windows (cmd/powershell)
+pip install -e .[dev]
+
+# Linux/macOS
+pip install -e ".[dev]"
+```
+
+## Command Line Arguments
+
+Run `navigate --help` for the complete list.
+
+- `-h`, `--help`: show help text.
+- `-c`, `--configurator`: open the configuration wizard.
+- `-sh`, `--synthetic-hardware`: launch without attached hardware.
+- `-d`: enable the debugging tool menu.
+- `--config-file PATH`: use a non-default `configuration.yaml`.
+- `--gui-config-file PATH`: use a non-default `gui_configuration.yml`.
+- `--experiment-file PATH`: use a non-default `experiment.yml`.
+- `--waveform-constants-file PATH`: use a non-default `waveform_constants.yml`.
+- `--waveform-templates-file PATH`: use a non-default `waveform_templates.yml`.
+- `--rest-api-file PATH`: use a non-default `rest_api_config.yml`.
+- `--logging-config PATH`: use a non-default `logging.yml`.
+- `--multi-positions-file PATH`: use a non-default `multi_positions.yml`.
+
+## Contributing
+
+If you plan to contribute, follow the contributor docs linked above. Before opening a PR, run:
+
+```bash
+pre-commit run --all-files
+pytest
+conda run -n navigate make -C docs html -j 15
 ```
 
-To test, run `conda activate navigate` and launch in synthetic hardware mode with `navigate
--sh`. Developers will have to install additional dependencies with
-`pip install -e '.[dev]'`.
-### Documentation
-Please refer to and contribute to the documentation, which can be found on GitHub Pages: [https://thedeanlab.github.io/navigate/](https://thedeanlab.github.io/navigate/).
-
-### Command Line Arguments
-
-Below are the optional arguments that can be passed to the navigate software:
-
-- `-h, --help`
-  Provides information on the optional arguments that can be passed to **navigate**.
-- `-sh, --synthetic_hardware`
-  Open the software without any hardware attached for testing
-  and setting up a new system.
-- `-c, --configurator`
-  Open the **navigate** configuration wizard, which provides a
-  graphical interface for setting up the hardware configuration.
-- `-d`
-  Enables the debugging menu in the software.
-- `--config-file`
-  Pass a non-default `configuration.yaml` file to **navigate**.
-- `--experiment_file`
-  Pass a non-default `experiment.yaml` file to **navigate**.
-- `--gui-config-file`
-  Pass a non-default `gui_config.yaml` file to **navigate**.
-- `--waveform-constants-file`
-  Pass a non-default waveform constants file to **navigate**.
-- `--rest_api_file`
-  Pass a non-default REST API file to **navigate**.
-- `--logging_config`
-  Pass a non-default logging configuration file to **navigate**.
+Need help or want to report a bug? Open an issue:
+<https://github.com/TheDeanLab/navigate/issues>