Reorganize page for Acquire Zarr

[melissawm]

This PR reorganizes the contents of the website to focus on acquire-zarr.

A few changes to take note:

• Footer and header items such as link to github and pypi have been replaced;
• get_started.md now includes the acquire-zarr README directly from github to ensure it stays up to date;
• I have wrapped the python and c examples from github as well, showing them as code blocks in the Examples section;
• the Acquire Imaging section concentrates the old contents of the website.

Preview here: https://melissawm.github.io/acquire-docs/dev/

[nclack]

Here are my comments from looking through the dev site:

I'd like to remove all references to "Acquire Imaging" from the front page and menu bar.

Filling out the "how to cite" section would be nice. I (just) added a zenodo doi (see acquire-project/acquire-zarr#56).

Looking at the "Guides" section of the front page:

• The "Python examples" and "C examples" point to code folders, but this content is different than what you get when you navigate via the menu (i.e. Examples>Python Examples).
  • Can we make these consistent? I really like the example pages (like here).
  • What do you think about linking out to the source code examples from the respective example pages?
• It looks like the "C examples" links to a folder of python examples.

Looking at the "Getting started" content:

• We should remove the "Building" section and just link to the acquire-zarr README for that. I suggest just having a blurb like: "Instructions for building the library are here".

acquire-zarr is both a C library and a python library. Where we refer to the library in python-specific contexts, I'd like to qualify that we're talking about the python acquire-zarr library. For example in the installation instructions on the front page, it should say something like "to install the acquire-zarr python library, pip install acquire-zarr"

[melissawm]

OOps! I was pretty sure I had fixed the examples links, will double check.

Will address your other feedback today.

I can manually add the citation from Zenodo, but would you like to also have a citation.cff file in the repo?

[nclack]

@aliddell do we have install/linking instructions for the c library anywhere? They would look something like:

1. Download the static library from the Releases
2. Install required dependencies
3. point people to the CMakeLists in the examples (or create a minimal cmakelists for folks to use)

[nclack]

citation.cff file in the repo?

I would! I just added one to acquire-project/acquire-zarr#56

[dgmccart]

• Remove the "About the Acquire Project" section on the front page and hide all Acquire imaging content
• Rename the reference to the website to "Acquire Zarr Streaming"
• On the front page, give the paragraph beneath the hero a header called "Background"
• In the installation section on the front page, add a subheader of "Install the Python Library" update the copy to: "To install the acquire-zarr python library on Windows, macOS, or Ubuntu, run the following command:" and subheader "Build the C Interface" add a paragraph beneath: "To build the C interface, follow these instructions" with a link to that section of the README
• Replace the Get Started page with markdown content containing all content in the README except the build instructions.
• Duplicate the Installation section from the front page in the Get Started page in a new section at the top of the page (beneath the description) called "Install the Python API"
• At the bottom of the Get Started page, add a section called "Building from Source" and link to the building section of the README. Add copy such as: "The library must be built from source to use the C interface or to use the Python library...[not sure what the difference is here from just installing the API]"

Questions for @aliddell:

• What are the instructions for users to install just the C interface of the library? Is that covered in the Building from Source section? Or are there instructions like the ones Nathan was asking about?
• Should we use "C library" or "C interface" as our terminology?
• Is it appropriate to have this section about building the C interface on the front page?

[melissawm]

I've just updated the preview with the feedback above, except for some copy around building the C library from source.

One question I have is that we have set up versioning for these docs, but now that the focus is changing from acquire-python to acquire-zarr, we may need to re-deploy the versions to match the acquire-zarr versions. Once we've settled on the versioning any maintainer can run the appropriate commands (which are described here https://acquire-project.github.io/acquire-docs/stable/for_contributors/update_version/)

[dgmccart]

• @aliddell and @nclack to discuss instructions for building the C library by itself and provide instructions to @melissawm (she has a draft in the Get Started page on the site)
• @aliddell and @melissawm to sync on python API reference (removing bases, attributes, methods from the header in lieu of listing attributes in a table)
• update terminology for C to be C library or C API in all places (remove C interface)
• @melissawm to test Talley's PR locally and tag @aliddell to review

[dgmccart]

New feedback on the Get Start Page.

In the current arrangement, the Python and C content is mixed together and out of order. To fix this:

• Make 2 top level headers: "Get Started with Python Bindings" and "Get Started with C Bindings"
• In the python section, have 2 subsections
• 1st subsection should be renamed "Installation the Python library" --> "Install the Python Library" and have "Usage" as a subheading in that section with the code that applies to python (2nd set of code in the current usage section)
• 2nd subsection of the python content should be "Build Python Bindings from Source" (notice title case capitalization - current was sentence case)
• In the "Get Started with C Bindings", 1st subsection has content "Build the C interface" --> rename to "Install the C Library" with a subsection "Usage" that has the C code (1st code block in the current Usage section)
• In the "Get Started with C Bindings", 2nd subsection "Building C Bindings from Source" duplicate the content from: https://melissawm.github.io/acquire-docs/dev/#build-the-c-interface
• Update all links on the Get Started that point to the README to point specifically to the "Building" section Anchor - https://github.com/acquire-project/acquire-zarr/blob/main/README.md#building

[aliddell]

@aliddell do we have install/linking instructions for the c library anywhere? They would look something like:

1. Download the static library from the Releases

2. Install required dependencies

3. point people to the CMakeLists in the examples (or create a minimal cmakelists for folks to use)

Yeah, on the acquire-zarr repo our only instructions are for building from source. I added a suggestion for getting started.

[dgmccart]

Yay! We are nearly done with the docs. Below are the remaining items:

• Under "For contributors", rename the pages to "Contribute to docs" and "Update docs version"
• Under "For contributors", add a page "Contribute to codebase" as the first article in the TOC. On the page, have the following paragraph "To contribute to the latest development version, build the libraries from source following these instructions to enable adding and testing changes locally before making a PR to the acquire-zarr repo. We especially welcome contributions of bug fixes, new features, and bindings in languages relevant to microscopy such as MATLAB and Julia."
• Update the site versioning to pull from acquire-zarr versions
• Finish remaining previously discussed updates to the API docs
• Incorporate Alan's feedback from below comments

@melissawm please tag me and Alan in a comment once these changes are live. I am so excited to be wrapping up this docs work!

[aliddell]

Got a few suggestions for you.

[melissawm]

Update the site versioning to pull from acquire-zarr versions

This will need to be done after this PR is merged, as it will take re-deploying the site so the new organization needs to go in first.

Finish remaining previously discussed updates to the API docs

Please let me know if I forgot anything. Here is the preview for the latest changes: https://melissawm.github.io/acquire-docs/stable/