At the moment, the header with 1st level navigation is only visible when you are at the top of the page, and as you scroll through the page, the site header scrolls over the navigation bar. This prevents the user from easily accessing other pages on the site while navigating through the pages. This created some friction for me when trying to navigate between the API documentation and other site pages. I suggest we keep the top-level headers visible regardless of where the user is on the page.

@melissawm

The homepage cards should render like this:

Instead the cards render like this:

In the getting started tutorial, the note admonition adds the code block to the TOC and has bad formatting.

@melissawm

The markdown file for this page has content, but the content does not render on the site.

Material for MkDocs uses a sponsorware model, and cards and card grids are currently sponsor-only: https://squidfunk.github.io/mkdocs-material/insiders/

We can re-create the cards manually if needed, but it will be bit of extra effort.

Copy for the Homepage

Header tagline: A python package providing a multi-camera video streaming library focused on performant microscopy

About Acquire

Acquire (acquire-imaging on PyPI) provides high-speed, multi-camera, video streaming and image acquisition with a programming interface#ADD LINK TO API REFERENCE for streaming video data directly to napari, Python and cloud-friendly file formats.

Installation

To install Acquire on Windows, macOS, or Ubuntu, simply run the following command:

python -m pip install acquire-imaging

Supported Cameras and File Formats

Acquire supports the following cameras (currently only on Windows):

• Hamamatsu Orca Fusion BT (C15440-20UP)
• Vieworks VC-151MX-M6H00
• FLIR Blackfly USB3 (BFLY-U3-23S6M-C)
• FLIR Oryx 10GigE (ORX-10GS-51S5M-C)

Acquire also supports the following output file formats:

• Tiff
• Zarr

For testing and demonstration purposes, Acquire provides a few simulated cameras, as well as raw and trash output devices.

Citing Acquire

Provide the CITATION.cff file

Acquire License

Acquire is provided under an Apache 2.0 license. You can learn more about the Apache license in the documentation here.

Copy for Homepage Tiles

Getting Started: Install Acquire and use simulated cameras

API Reference: Information on classes and methods

Tutorials: Guides on using Acquire for specific tasks

For contributors: Learn how to contribute code or documentation to Acquire

Copy for the Tutorials Homepage

Description for the region above the tiles: These tutorials will help you explore the main use cases of Acquire and show examples of using the API. Please submit an issue on Github if you'd like to request a tutorial, or if you are also interested in contributing to a tutorial to this documentation please visit our contribution guide#ADD LINK!

Tiles titles (no descriptions provided):

1. Finite Triggered Acquisition
2. Access Data from the Camera
3. Livestream to napari or Matplotlib
4. Select a Streaming or Storage Device
5. Test Camera Drivers
6. Setup Triggers
7. Setup Acquisition Properties
8. Storage Devices In-Detail
9. Save Compressed Data
10. Save Multiscale Data
11. Save Chunked Data

No description below tiles.

The logos in the header are broken images.

@melissawm

On Firefox and chrome, android:

I will investigate asap.

The API for configuring chunking has changed in the latest release. Now you don't have to specify the chunk size in bytes. Instead, you set all the chunk dimensions.

So for example, where before you had

# assuming 1920 x 1080 images with mono8 pixels
config.video[0].storage.settings.chunking.max_bytes_per_chunk = 32 * 2**20 # 32 MB chunks
config.video[0].storage.settings.chunking.tile.width = 1920 // 2
config.video[0].storage.settings.chunking.tile.height = 1080 // 2

which would give you 64 frames in a chunk, you can configure it like so:

config.video[0].storage.settings.chunk_dims_px.width = 1920 // 2
config.video[0].storage.settings.chunk_dims_px.height = 1080 // 2
config.video[0].storage.settings.chunk_dims_px.planes = 64

We'd like to autogenerate our API docs by reading doc strings in the pyi file.

I've noticed a few of the image assets are missing when I go to the site.

I can't check out recent commits because Windows refuses to create a file with a . at the end. Also, our "for contributors" page looks like this:

For each tutorial on the website, provide a python file for the user to download. We'd like to automate this process to avoid needing to keep track of updates as content on the website changes. Mkdocs gallery may be a suitable solution. @melissawm

Running list of new content needs/requests for the Acquire Docs Site:

• Update API and tutorials for changes to chunking from 0.2.0 - discuss with Alan - getting started, multiscale, and API impacted
• writing metadata with tiff filetype [tiff-json not working issue]
• livestream example with matplotlib
• writing metadata with zarr
• Contribution guide (expanded version of quickstart)
• Content based on Allen Cell usage (diSpim-UI and iSpim-control) - instrument_parameters.py file, main set up of acquire with be in the frame_grabber.py file and ispim.py file
• Tutorials based on user needs
• Code contribution guide

A few design items still need to be implemented:

• Zulip logo/link in top navbar - #14
• GitHub, Zulip and PyPI logos/links in footer - #14
• Footer styling and display of html elements (i.e. text alignment) - #14
• Hover color (blue) for Prev/Next links - #15
• Dark mode?
• Domain name
• Admonition styling - #13
• Syntax highlighting - #17
• Mobile menu - #16
• Link styling - #57
• Logos in header/footer are inconsistent in different pages - #30, #50

Feel free to edit this issue with more items as they show up.

We'd like to introduce versioned docs since new releases may introduce breaking changes. Read the docs may be an option for hosting versioned docs for free using a tag on the docs to assign the version. @melissawm will explore if mkdocs is compatible with read the docs.

In navigating the docs site, I am often trying to click on the Acquire Docs header to direct me to the home page. Perhaps we could add a redundant link there.

As part of the Acquire user-facing documentation, we'll include several tutorials and supporting materials on how to utilize Acquire and integrate Acquire API into existing workflows. This issue is a running list of ideas and a tracker of work.

Tutorials:

• Getting Started guide from Alan's tutorial
• Finite Triggered Acquisition from Nathan's tutorial
• Livestreaming to napari
• Examples of properties and triggers JSON files - PR1 and PR2
• How to access images off of the camera (framedata)
• Simple example of setting up camera - identifier, where to store images, etc.
• Using runtime start/stop/get state
• doc contribution quickstart

Tutorials from Tests:

• select vs select_one_of
• camera discovery
• setting storage
• zarr compression
• zarr chunking
• zarr multiscale
• using acquire.setup

The drivers.md tutorial doesn't render properly on the website. The tutorial title shows up as None.

The tutorial itself doesn't render properly.

When the PR was merged, there was a conflict in mkdocs.yaml, so perhaps the conflict wasn't resolved correctly?

You can provide direct linking to subsections of a page if you click on the section in the right hand TOC and manually copy the URL. Is it possible to add a copiable anchor link next to the headings themselves? Example below:

Multiple variable names for the same type of object were used in tutorials. To make it easier for the user to utilize examples from multiple tutorials, these variable names should be standardized. Ditto for configuration settings where applicable. There are also some formatting errors and/or areas of improvement.

To prepare for an internal review of content:

• Standardize variable names throughout tutorials
• Standardize configuration settings (e.g. image size, max frames collected, etc.) except for where unique settings are needed to teach the concept
• Review API documentation and improve descriptions
• Adjust code comments so that they fit inside the window without horizontal scrolling
• Review and improve formatting of tutorials
• Add internal links to other tutorials where applicable
• Implementation of homepage tiles
• Move example JSON files and fix references
• Internal links instead of URLs

We have several tutorials already on the site. To help users find what their looking for, we should organize these tutorials into larger categories.