Refining documentation

[d33bs]

Summary by CodeRabbit

• Documentation
  • Added "Getting Started" guide and "Catalog Setup" guide for catalog-backed workflows
  • Expanded README with a "Troubleshooting" section and clarified Cytomining/Zarr wording
  • Updated docs and examples to standardize catalog namespace usage and clarify alias normalization and overwrite behaviors
• Chores
  • Adjusted docs build to disable notebook execution in CI to improve build reliability

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ca3852e2-914e-47bd-b984-7083267cd7b2

📥 Commits

Reviewing files that changed from the base of the PR and between b7b0d84 and fdceb68.

📒 Files selected for processing (1)

• README.md

✅ Files skipped from review due to trivial changes (1)

• README.md

---

📝 Walkthrough

Walkthrough

CI workflows and Sphinx config now disable MyST-NB execution during docs builds via MYST_NB_EXECUTION_MODE=off. New Getting Started and Catalog Setup docs were added; README and multiple docs updated to standardize catalog namespace to bioimage.cytotable and add troubleshooting guidance.

Changes

Cohort / File(s)	Summary
CI Workflow Configuration .github/workflows/publish-docs.yml, .github/workflows/run-tests.yml	Prefix Sphinx build commands with MYST_NB_EXECUTION_MODE=off to prevent MyST-NB from executing notebooks in CI.
Sphinx Documentation Config docs/src/conf.py	Imported os and added nb_execution_mode for myst_nb, reading MYST_NB_EXECUTION_MODE from the environment (default "off").
Getting Started & Catalog Setup README.md, docs/src/getting-started.md, docs/src/catalog-setup.md, docs/src/index.md	Added Getting Started and Catalog Setup pages; README expanded with Start Here, troubleshooting, and CLI examples; index TOC updated to include new pages.
Documentation Namespace & Wording Updates docs/src/cytomining.md, docs/src/duckdb.md, docs/src/workflow.md	Standardized catalog namespace examples to bioimage.cytotable, adjusted Cytomining framing and Zarr wording, and updated related CLI examples.
Example Docs Clarifications docs/src/examples/basic-workflow.ipynb, docs/src/examples/basic-workflow.py	Clarified wording that alias normalization applies along "join and export paths"; no executable changes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• d33bs/iceberg-bioimage#1 — Implements the same GitHub Actions workflow changes and Sphinx config updates to honor MYST_NB_EXECUTION_MODE, closely related to these edits.

Poem

🐰 I hopped through docs and tidied the trail,

Names set to bioimage.cytotable without fail,
Notebooks stay quiet while pages compile,
Getting-started signs guide every mile,
A tiny rabbit cheers — docs neat and agile! 🥕📚

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Refining documentation' is vague and generic, using non-descriptive language that fails to convey the specific nature of the documentation changes.	Consider a more specific title that highlights the primary documentation improvements, such as 'Add getting started guide and catalog setup documentation' or 'Improve documentation with setup guides and troubleshooting section'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refinement

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

README.md (1)

57-58: Consider clarifying the sentence structure.

The phrase "allows either Zarr 2 or Zarr 3 runtimes so optional forward-facing integrations" reads slightly awkwardly. Consider adding "that" for clarity.

📝 Suggested rewording

-- The base package allows either Zarr 2 or Zarr 3 runtimes so optional
-  forward-facing integrations can coexist in the same environment
+- The base package allows either Zarr 2 or Zarr 3 runtimes so that optional
+  forward-facing integrations can coexist in the same environment

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 57 - 58, Update the README sentence to improve
clarity by inserting "that": change "The base package allows either Zarr 2 or
Zarr 3 runtimes so optional forward-facing integrations can coexist in the same
environment" to "The base package allows either Zarr 2 or Zarr 3 runtimes so
that optional forward-facing integrations can coexist in the same environment"
(edit the README.md text where this sentence appears).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@README.md`:
- Around line 57-58: Update the README sentence to improve clarity by inserting
"that": change "The base package allows either Zarr 2 or Zarr 3 runtimes so
optional forward-facing integrations can coexist in the same environment" to
"The base package allows either Zarr 2 or Zarr 3 runtimes so that optional
forward-facing integrations can coexist in the same environment" (edit the
README.md text where this sentence appears).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c519ed06-1eb8-4358-9600-694f14811faf

📥 Commits

Reviewing files that changed from the base of the PR and between 7fa773c and b7b0d84.

📒 Files selected for processing (12)

• .github/workflows/publish-docs.yml
• .github/workflows/run-tests.yml
• README.md
• docs/src/catalog-setup.md
• docs/src/conf.py
• docs/src/cytomining.md
• docs/src/duckdb.md
• docs/src/examples/basic-workflow.ipynb
• docs/src/examples/basic-workflow.py
• docs/src/getting-started.md
• docs/src/index.md
• docs/src/workflow.md