further improvements of docs

[jepegit]

Context

The cellpy 2.x docs have a solid skeleton (Getting started → Tutorials →
How-to guides → Concepts → Reference), but they are still written mostly from
the inside out: they describe what cellpy has, rather than answering the
questions a user actually arrives with.

The typical cellpy user is a battery scientist with good electrochemistry
knowledge and limited Python experience. When that person hits trouble —
a file will not load, capacities look wrong, the units are not what they
expected, they do not know which column holds what — there is currently no
page in the docs that meets them there.

Concrete gaps found in a first pass:

• No troubleshooting / FAQ page at all. Nothing indexed by error message
  or symptom ("NotImplementedError", "no cycles found", "capacity is zero",
  "cannot read .res on Linux").
• No glossary and no units page. Nothing that maps battery-science
  vocabulary onto cellpy names, and nothing that states plainly what unit a
  mass, capacity, or current is in, or how to change it.
• No CLI reference. The cellpy command-line tool is used in setup and
  checkup pages, but its subcommands are not documented anywhere.
• No task index / cookbook. A user who knows what they want ("plot cycle
  life", "export to Excel for Origin", "get areal capacity") has to guess
  which tutorial contains it.
• Column-level reference is thin. fundamentals/data_structure.md
  explains the shapes but not what each column means or its unit.
• Discoverability. Several good answers already exist in the docs but are
  buried inside long tutorials with no entry point from the navigation.

Goal

Iteratively improve the documentation by repeatedly role-playing a cellpy
user who runs into trouble — mostly the limited-Python / strong-science
persona, but also occasionally a complete newcomer and an experienced
Python developer — and then fixing whatever the docs failed to answer.

Approach

A series of small, focused pull requests. Each iteration:

1. Adopt a specific user persona and a specific realistic problem.
2. Try to answer it using only the published docs.
3. Write or restructure whatever was missing or unfindable.
4. Wire the new material into zensical.toml navigation and cross-link it
   from the pages the user would actually be on.
5. Green CI (essential, full, and the Docs link-check build), then merge.

Acceptance criteria

• Each iteration lands as its own merged PR with green CI.
• The docs build stays link-clean (the Docs workflow fails on any
  broken link or missing anchor).
• New pages are reachable from zensical.toml navigation, not orphaned.
• Content is verified against the actual code, not assumed — every code
  snippet and every option name checked against the source or run.
• Writing stays at the level of a scientist who is not a programmer:
  concrete, task-first, minimal jargon, no unexplained Python idioms.

[jepegit]

Ten iterations done

All ten shipped as separate PRs, each with green CI (essential, full and
the link-checking Docs build) and merged to master.

#	PR	Persona / trigger	Added
1	#1024	scientist whose Arbin file will not load	troubleshooting.md — symptom-indexed
2	#1025	cannot tell what unit a capacity is in	guides/units.md
3	#1027	wants to see the cell they just loaded	guides/plotting.md
4	#1029	staring at a 67-column example spreadsheet	guides/batch_database.md
5	#1030	prefers the command line	reference/cli.md
6	#1031	needs the numbers in Excel / Origin / a paper	guides/exporting.md
7	#1032	58 summary columns, no idea which one	reference/summary_columns.md
8	#1033	capacity missing for some cycles	guides/step_table.md
9	#1034	complete newcomer, limited Python	getting_started/first_hour.md + extras table
10	#1035	knows what they want, not where it is	how_do_i.md

Every code snippet in the new pages was executed against the bundled example
data (and, for the batch pages, the bundled example database) rather than
written from the source and hoped for.

Doc bugs found and fixed along the way

• cycle_mode="full-cell" (hyphen) in the loading tutorial — not a recognised
  spelling, so cellpy silently fell back to the normal convention and logged a
  warning.
• cumulated_capacity_throughput in the data-structure page — no such schema
  field; it is test_cumulated_capacity_throughput.
• c.to_excel(out_folder) in the file-formats page — to_excel takes a file
  name; passing a directory raises PermissionError.
• The step-type list in the data-structure page advertised charge_cv,
  discharge_cv and not_known, none of which the classifier emits, and
  omitted the empty string it actually uses for uncategorized steps.
• c.get_ocv(ocv_type=..., cycle_number=...) in Basic usage — neither parameter
  exists; the call raises TypeError. (I swept every other c.<method>(...)
  call in the non-notebook docs against its signature; this was the only wrong
  one.)
• Two of my own pages: the bare charge_capacity column is in raw_units
  (what the tester wrote), not in cellpy_units — only the
  _absolute / _gravimetric / _areal variants carry the unit conversion.
  For an Arbin .res file that is a factor of 1000. Corrected in docs: summary-column reference, and a units correction (iteration 7 of #1023) #1032.

Code issues found, filed separately

• cycles_plot with matplotlib backend crashes when all selected cycles are formation cycles #1026 — cycles_plot(..., backend="matplotlib") raises
  ValueError: arange: cannot compute length when every selected cycle is a
  formation cycle. Labelled yolo.
• Default cellpy_file_extension is still "h5" while the native v2 format is ".cellpy" #1028 — the shipped default cellpy_file_extension is still "h5" while the
  native v2 format is ".cellpy". Affects the fresh-install batch path: cellpy
  files are looked for (and written) as .h5, which needs the
  legacy-files extra a default pip install cellpy does not have.

Where the docs stand now

Navigation gained two top-level entries (How do I…?, Troubleshooting),
five how-to guides, two reference pages and one getting-started on-ramp. The
Docs workflow fails on any broken link or missing anchor, and it is clean.

Leaving this issue open — the obvious next passes are the tutorial notebooks
(rendered from examples/*.ipynb, so they need a different workflow than the
hand-written pages), a glossary of battery terms as cellpy spells them, and a
pass aimed at the experienced-Python persona (typing, extending, the plugin
surface), which these ten iterations deliberately under-served.

[jepegit]

Next pass: usability review of the docs

A review of how easy the published docs (latest, built from master at e766f365) are to use is in
.issueflows/04-designs-and-guides/docs-usability-review.md.
It gives each problem with evidence, a concrete fix and a priority (P1–P3), and ends with an order of work in issue-sized chunks.

The structure from the ten iterations above holds up well. What still gets in the way:

• Tutorials (the next pass already named above):
  • four links point to .ipynb files that aren't on the site, in 01_loading_data.md and 06_loading_different_formats.md;
  • 01 and 02 load a data/…res file the reader doesn't have;
  • most pages start straight with import lines and no introduction;
  • 08_batmo_bdf is 1752 lines, mostly full data tables;
  • the order sends learners through four file-format pages before any analysis.
• Getting started has 11 entries. The three agent/MCP pages and the two migration pages crowd the newcomer path.
• Pages missing from the nav or filed in the wrong folder. writing_a_cli_plugin.md, adapted_readme.md and cursor-issue-workflow.md aren't in the nav. remote_paths, writing_a_loader_plugin and configuration_reference live in a different source folder from their nav section.
• API pages are very large. api/readers/ is 1.7 MB (~150 objects) and api/utils/ is 1.6 MB. Of the 90 public CellpyCell methods, 8 have no docstring and only 5 have an example.
• No images in the guides. The plotting, ICA, step-table and units guides have none.
• Link-check gap. The Docs workflow doesn't catch links to non-page files such as .ipynb.

Suggested chunks

1. Quick P1 fixes, one PR (fits yolo): landing-page H1, the .ipynb links, nav/H1 title mismatches, orphan pages, the API "where to look" table, and extending the link check.
2. Tutorial framing: data source, intro and download header from the render script, shorter tables.
3. Nav restructure: agent and upgrade sections, move files to match the nav, redirects.
4. Landing page and theme.
5. Figures and a pipeline diagram.
6. API: split CellpyCell onto its own page, docstrings.