Skip to content

docs: indent struct-field descriptions to 4 spaces - #695

Merged
edkerk merged 1 commit into
develop3from
fix/docstring-continuation-indent
Aug 25, 2026
Merged

docs: indent struct-field descriptions to 4 spaces#695
edkerk merged 1 commit into
develop3from
fix/docstring-continuation-indent

Conversation

@edkerk

@edkerk edkerk commented Aug 25, 2026

Copy link
Copy Markdown
Member

Problem

Building the RAVEN documentation site emits 18 warnings of the form:

griffe: analysis/sampleCHRR.m:42: Confusing indentation for continuation line 41 in docstring, should be 4 spaces, not 2
griffe: gapfilling/gapFillTopological.m:45: Confusing indentation for continuation line 44 in docstring, should be 4 spaces, not 2

Both come from the same pattern — a struct-valued return whose fields are
listed at 2 spaces:

% info : struct with fields:
%   .nDimensions  — dimension of the sampled flux polytope

In numpydoc style, a description continuation must be indented 4 spaces
relative to the entry name. At 2 spaces the field list is not reliably read as
part of the entry, so it can render outside it on the generated API page.

Fix

Indent the field lines to 4 spaces, and give both entries the plain type
struct. That matches analysis/compareFluxes.m, which documents a struct
return the same way and produces no warnings:

% result : struct
%     .turnedOn  — cell, rxn IDs newly active in fluxes2

Documentation only — no functional change.

Verification

With these two files in place, mkdocs build --strict in the docs site reports
zero "Confusing indentation" warnings, down from 18.

Found while writing the flux-variability and gap-filling pages of the new
user guide.

The `info` return of sampleCHRR and the `result` return of
gapFillTopological listed their fields at 2 spaces of indentation. In
numpydoc style a description continuation must be indented 4 spaces
relative to the name, so the docs generator reported "Confusing
indentation for continuation line" 18 times and the field lists risked
rendering outside their entry.

Indent the field lines to 4 spaces and give both entries the plain type
`struct`, matching compareFluxes.m, which documents a struct return the
same way without warnings.

Documentation only; no functional change.
@github-actions

Copy link
Copy Markdown

Function test results

300 tests   274 ✅  1m 18s ⏱️
 25 suites   26 💤
  1 files      0 ❌

Results for commit 19354cc.

@edkerk
edkerk merged commit 2282883 into develop3 Aug 25, 2026
4 checks passed
@edkerk
edkerk deleted the fix/docstring-continuation-indent branch August 25, 2026 21:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant