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).

  • 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 ImageOperation Docstring Style Guide 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:

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:

import phenotypic as pht

Import specific operations directly when demonstrating them:

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:

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 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 ImageOperation Docstring Style Guide).

Use Sphinx cross-references where possible:

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

In MyST 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#

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

Reference List Format#

## 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#

# 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