# Documentation Writing Guide

This guide defines PhenoTypic's documentation structure, voice, and conventions.
All user-facing documentation follows the Diataxis framework [1], which organizes
content into four modes based on the reader's needs.

## Documentation Structure

PhenoTypic's documentation is organized into five top-level sections.

### Tutorials

**Purpose:** Guided lessons that teach through doing. Each tutorial builds on the
previous, forming a sequential learning path.

**Format:** Jupyter notebooks with Plotly interactive visualizations.

**Characteristics:**

- The reader follows step-by-step instructions and observes results.
- Every code cell must be runnable against the bundled sample data.
- Tutorials teach *one concept at a time* -- don't combine detection and
  measurement in a single tutorial unless the tutorial is about pipelines.
- End each tutorial with a concrete outcome: "You now have a working pipeline
  that detects and measures colonies."

### How-To Guides

**Purpose:** Task-oriented recipes that solve a specific problem. The reader
already knows the basics and needs to accomplish something concrete.

**Format:** Jupyter notebooks for visual tasks; static MyST Markdown pages for
CLI, configuration, and non-visual workflows.

**Characteristics:**

- Start with the goal, not the background: "To correct vignetting before
  detection, apply `VignetteCorrector` as the first pipeline step."
- Assume tutorial-level familiarity -- don't re-explain what an `ImagePipeline` is.
- Each guide is standalone. Readers arrive from search or cross-references, not
  by reading sequentially.
- Link to Explanation pages for theory; link to API Reference for parameter
  details.

### Explanation

**Purpose:** Conceptual material that builds understanding. Explains *why* things
work the way they do, not *how* to use them.

**Format:** Static MyST Markdown pages with diagrams and annotated images.

**Characteristics:**

- No prerequisite code to run. Light code is acceptable for illustration, but
  the reader should gain understanding from the prose alone.
- Discuss tradeoffs, failure modes, and design decisions.
- Reference literature where appropriate using IEEE citation style (see
  [References and Citations](#references-and-citations)).
- These pages are the target of "See Also" links from docstrings and how-to
  guides.

### Extending PhenoTypic

**Purpose:** Dedicated section for users who want to build custom operations,
plotters, or dashboards on top of PhenoTypic's ABC hierarchy.

**Format:** Mini-Diataxis structure within the section -- contains its own
tutorial (notebook), how-to guides (static pages), and explanation pages.

**Characteristics:**

- The tutorial walks through creating a complete custom `ImageEnhancer` from
  scratch.
- How-to guides cover each ABC type (`ObjectDetector`, `ObjectRefiner`,
  `MeasureFeatures`, etc.) as standalone recipes.
- Explanation pages cover the ABC hierarchy, the `_operate()` contract, and the
  component registry system.

### API Reference

**Purpose:** Information-oriented reference for every public class, function, and
parameter. Auto-generated from docstrings via `sphinx-apidoc` and `autodoc`.

**Format:** RST pages generated by the Sphinx build. Not manually authored.

**Characteristics:**

- Accuracy depends entirely on docstring quality -- see
  [](docstring_style.md) for the docstring template.
- Supplemented by manually authored pages: CLI reference, configuration
  reference, and glossary.

## Audience

The primary audience is **microbiologists and biologists who are new to
computational image processing** and have limited Python experience. They know
variables, loops, imports, and can install packages, but may not be familiar with
NumPy arrays, image representations, or scientific Python conventions.

A secondary audience is **researchers with image processing experience** who are
evaluating PhenoTypic for their phenotyping workflows. They need efficient access
to capabilities and parameters without wading through introductory material.

### External Concept Linking Policy

Do not explain Python or NumPy basics inline. When a concept requires prerequisite
knowledge, link to an authoritative external resource:

```markdown
Colony sizes are returned as a [NumPy array](https://numpy.org/doc/stable/user/basics.html)
with one entry per detected object.
```

Common external references:

- NumPy array basics: `https://numpy.org/doc/stable/user/basics.html`
- Python pathlib: `https://docs.python.org/3/library/pathlib.html`
- pandas DataFrames: `https://pandas.pydata.org/docs/user_guide/dsintro.html`
- Matplotlib basics: `https://matplotlib.org/stable/tutorials/introductory/usage.html`

## Voice and Tone

Each documentation section has a distinct voice matched to the reader's mindset.

### Tutorials -- Encouraging and Guided

Second person, active voice. Celebrate milestones. The reader is learning and
needs reassurance.

```
# Good
"Let's load our first plate image and see what we're working with."
"You now have a complete pipeline that enhances, detects, and measures colonies."

# Bad
"The user should load an image using the imread method."
"The pipeline has been successfully constructed."
```

### How-To Guides -- Direct and Efficient

Imperative voice. State the goal, then the solution. No preamble or motivation --
the reader already knows *why* they're here.

```
# Good
"Pass `method='triangle'` to detect faint colonies against noisy backgrounds."

# Bad
"In some cases, you might want to consider using a different threshold method.
The triangle method can be useful when colonies are faint."
```

### Explanation -- Textbook-Lite

Semi-formal, third person. Structured prose with diagrams. It is acceptable to
reference literature and use domain-specific terminology with definitions.

```
# Good
"Otsu's method minimizes intra-class variance by exhaustively searching for
the threshold that best separates the foreground and background intensity
distributions [2]. This works well when the histogram is bimodal -- a
common property of well-lit plates with uniform backgrounds."

# Bad
"So basically Otsu's just finds the best cutoff between dark and light pixels."
```

### Extending -- Mentor

First person plural or second person. Conversational but precise. Guide the
reader through decisions.

```
# Good
"The simplest operation to start with is an enhancer, since it only modifies
detect_mat. You don't need to worry about objmask, objmap, or grid state."

# Bad
"ImageEnhancer subclasses shall implement the _operate method which receives
an Image instance and returns a modified Image instance."
```

## Domain Language

Use microbiology terminology consistently. Avoid generic image processing jargon
when a domain-specific term exists.

| Use | Instead of |
|-----|------------|
| colony | blob, object, region |
| inoculum | seed point, starting blob |
| plate | image (when referring to the physical plate) |
| well | grid cell, section (when referring to physical wells) |
| grid section | cell, tile (when referring to the computational grid partition) |
| hyphae / mycelium | filaments, branches (when biologically accurate) |
| detect_mat | detection matrix, enhanced grayscale |
| objmask | binary mask, foreground mask |
| objmap | label map, labeled array |

When a term has both a biological and computational meaning (e.g., "colony" vs.
"connected component"), use the biological term in tutorials and how-to guides,
and introduce the computational term in Explanation pages.

## Code Conventions

### Imports

Always use the canonical import alias:

```python
import phenotypic as pht
```

Import specific operations directly when demonstrating them:

```python
from phenotypic.detect import OtsuDetector
from phenotypic.enhance import GaussianBlur, EnhanceLocalContrast
```

### Sample Data

All tutorials and visual how-to guides use the **bundled real plate images**
located in `src/phenotypic/data/SnP_images/`. There are two organisms, each with
a cropped and a full-plate variant:

| Image | File | Use when |
|-------|------|----------|
| Rhodotorula yeast (cropped) | `RhodotorulaYeastCropped.png` | Default for most tutorials and how-tos. Round colonies, standard 96-well grid, clean background. |
| Neurospora filamentous fungi (cropped) | `NeurosporaFilamentousFungiCropped.png` | Filamentous fungi tutorials and how-tos. Irregular hyphal morphology, spreading growth. |
| Rhodotorula yeast (full plate) | `RhodotorulaYeastFullPlate.png` | Operations that need the full uncropped plate: cropping, padding, vignetting correction, color correction. Includes a color checker. |
| Neurospora filamentous fungi (full plate) | `NeurosporaFilamentousFungiFullPlate.png` | Full plate variant for fungi-specific correction workflows. Includes a color checker. |

**When to use which variant:**

- **Cropped images** are the default. Use these for detection, enhancement,
  measurement, pipeline building, and grid plate tutorials.
- **Full plate images** include the plate border, scanner margins, and a
  **color checker** (for `ColorCorrector` / `ColorCheckerProfile`). Use these
  for tutorials and how-tos that demonstrate cropping (`ImageCropper`), padding
  (`ImagePadder`), vignetting correction (`VignetteCorrector`), or color
  correction.

For docstring smoke tests (in the test suite, not in docstrings), use
`load_synth_yeast_plate()` (synthetic, fast, no file I/O dependencies).

### Visualization

Use Plotly interactive figures via the `.dash()` method, which returns
`plotly.graph_objects.Figure`:

```python
image.dash()                              # RGB display (Plotly interactive)
image.detect_mat.dash()                   # Detection matrix (Plotly interactive)
image.objmap.dash()                       # Labeled objects (Plotly interactive)
image.dash(overlay=True)                  # Detection overlay (Plotly interactive)
image.dash(overlay=True, show_labels=True)  # Overlay with colony labels
```

The `.show()` method returns `(matplotlib.figure.Figure, matplotlib.axes.Axes)`
and is appropriate for static diagrams in Explanation pages or when matplotlib
output is explicitly needed.

Follow the project's Okabe-Ito color palette (defined in
`docs/style_guide/dashboards/CLAUDE.md`) for any custom Plotly figures.

In tutorials and how-to notebooks, prefer `.dash()` for interactive
visualizations. Do not use `matplotlib.pyplot` (`plt.show()`, `plt.imshow()`)
directly. The `.show()` method (matplotlib) is acceptable in Explanation pages
for static diagrams.

### Notebook Structure

Every tutorial and how-to notebook follows this cell pattern:

1. **Title cell** (Markdown): `# Tutorial N: Title`
2. **Imports cell** (Code): all imports, no output
3. **Data loading cell** (Code): load sample image, display it
4. **Teaching cells** (alternating Markdown + Code): one concept per pair
5. **Summary cell** (Markdown): what the reader accomplished, link to next step

## Cross-Referencing

Link between documentation sections to help readers navigate.

- **Tutorials** link forward to related how-to guides: "For more on contrast
  enhancement, see [How to enhance low-contrast images](../how_to/notebooks/enhance_low_contrast)."
- **How-to guides** link to Explanation pages for theory and to API Reference for
  parameter details.
- **Explanation pages** link to relevant how-to guides for practical application.
- **Docstrings** link to Explanation pages via `See Also` (see
  [](docstring_style.md)).

Use Sphinx cross-references where possible:

```rst
:class:`phenotypic.detect.OtsuDetector`
:doc:`/explanation/detection_strategies`
:meth:`Image.show`
```

In MyST Markdown:

```markdown
{class}`phenotypic.detect.OtsuDetector`
{doc}`/explanation/detection_strategies`
```

## References and Citations

Use **IEEE citation style** [3] for all literature references. Place a numbered
reference list at the bottom of any page that cites external work.

### Inline Citation

```markdown
Otsu's method minimizes intra-class variance to find an optimal threshold [2].
```

### Reference List Format

```markdown
## References

[1] D. Procida, "Diataxis: A systematic framework for technical documentation,"
2023. [Online]. Available: https://diataxis.fr/

[2] N. Otsu, "A threshold selection method from gray-level histograms," *IEEE
Trans. Syst., Man, Cybern.*, vol. 9, no. 1, pp. 62--66, Jan. 1979.
```

### When to Cite

- Algorithm descriptions in Explanation pages (always cite the original paper).
- Docstrings that name a specific method (e.g., Otsu, Frangi, BM3D) -- include a
  `References` section in the docstring.
- Tutorials and how-to guides generally do not need citations; link to the
  relevant Explanation page instead.

## Building the Documentation

```bash
# Full build (regenerates API docs, then builds HTML)
cd docs && make html

# Quick rebuild (HTML only, skips apidoc regeneration)
cd docs && sphinx-build -n -b html source build/html

# Verify notebook execution
uv run jupyter execute docs/source/tutorials/notebooks/<notebook>.ipynb
```

The `nbsphinx_allow_errors` setting must remain `False` -- any notebook that
fails to execute will break the build. Test notebooks locally before committing.

## References

[1] D. Procida, "Diataxis: A systematic framework for technical documentation,"
2023. [Online]. Available: https://diataxis.fr/

[2] N. Otsu, "A threshold selection method from gray-level histograms," *IEEE
Trans. Syst., Man, Cybern.*, vol. 9, no. 1, pp. 62--66, Jan. 1979.

[3] IEEE, "IEEE reference guide," 2024. [Online]. Available:
https://ieee-dataport.org/sites/default/files/analysis/27/IEEE%20Citation%20Guidelines.pdf