Skip to content

Report Standards

This document specifies the required structure and conventions for all reports, charts, and word/phrase studies produced by this project.

Contents

Build Script Requirement

Every report must have a reproducible build script. Never produce a report file without a build script that generates it.

What Where
Build script scripts/build_<term>_report.py
Generated report mkdocs_src/reports/<corpus>/<category>/<term>/
Generated charts mkdocs_src/reports/<corpus>/<category>/<term>/ or charts/<corpus>/<category>/<term>/
Generated CSVs Same directory as the report

Running the build script from repo root must regenerate all charts, CSVs, and the report .md file from scratch.

Output Directory Layout

Every word/phrase study lives in its own named subdirectory — never flat in the parent category folder.

mkdocs_src/reports/
    both/
        word_studies/
            fasting/
                fasting_word_study.md
                fasting-ot-distribution.png
                fasting-nt-distribution.png
                fasting-data.csv
                README.md   ← index for this study
        index.md            ← corpus-level index
    ot/
        ...
    nt/
        ...
    index.md                ← top-level quick links

CSV Exports

Every report build script must export the underlying data as CSV alongside the report. The CSV filename should match the report name:

fasting_word_study.md  →  fasting-data.csv   (or fasting_word_study.csv)

CSVs are the portable, tool-agnostic record of the data. They must be committed alongside the report.

README Indexes

Every output directory (reports/, charts/, sub-categories) must have a README.md with:

  • A brief description of what the directory contains
  • A table of contents with links to all files/subdirectories

This is for non-technical users who browse the repository directly on GitHub.

Long Report Structure

Any report with more than approximately five ## sections must open with:

  1. ## Contents — a TOC with anchor links to every ## section
  2. ## Key Observations — a brief executive summary of the most important findings

Both sections appear before the body sections.

## Contents

- [Distribution by Book](#distribution-by-book)
- [Collocations](#collocations)
- ...

## Key Observations

- The term appears 58× in the OT, concentrated in Psalms (14×) and Isaiah (9×).
- ...

## Distribution by Book
...

Overview Page Registration

When adding a new report, register it in all three of the following places (never just one or two):

  1. mkdocs_src/reports/index.md — the top-level Quick Links list, under the appropriate section heading
  2. mkdocs_src/reports/<corpus>/index.md — the corpus-level index table (e.g. both/index.md, ot/index.md, nt/index.md)
  3. mkdocs_src/reports/<corpus>/<category>/index.md — the category index table (e.g. both/word_studies/index.md)

Also add an entry to mkdocs_nav.yml under the correct nav section.

Table Summary Rows

Tables on the site are sortable by column click. Rows whose first cell is bold and whose text matches the word "total" (case-insensitive) are treated as summary rows and are always pinned to the bottom, regardless of the sort order.

Convention — summary row format:

| **OT Total** | **408** | **305,094** | **1.34** | |
| **NT Total** | **362** | **141,746** | **0.26%** |
| **Total**    | **47**  | **100%** |

Rules: 1. The first cell bold text must contain the word "total" (e.g. **Total**, **OT Total**, **NT Total**, **Grand Total**). 2. All other cells in a summary row should also be bold for visual consistency. 3. Do not bold the first-column cell of regular data rows solely to trigger summary-row pinning — use the "total" convention instead. 4. Regular data rows may use bold in the first column for emphasis (e.g. bolded term names in glossary tables). They sort normally.

The CI check bold-summary-row (scripts/validate_tables.py) warns when a table row has every cell bold but the first-cell text does not match "total" — which suggests the author intended a summary row but used the wrong convention.

Notebooks

When adding a new feature or data source, update the relevant Jupyter notebook(s) to demonstrate the feature. Notebooks live in notebooks/ and are the primary interactive exploration surface.

Code Quality in Build Scripts

  • No lint directives in output strings. Never place # noqa, # type: ignore, or any other tool comment inside a string literal that gets written to a file — they become literal text in the output. Instead, add the script to per-file-ignores in setup.cfg to suppress linter warnings on long string literals.
  • All build scripts must pass flake8 and mypy before commit.