Skip to content

refactor: restructure the api docs (4/4) - #1287

Draft
selmanozleyen wants to merge 12 commits into
feat/enum-to-literalfrom
feat/api-docs-restructure
Draft

refactor: restructure the api docs (4/4)#1287
selmanozleyen wants to merge 12 commits into
feat/enum-to-literalfrom
feat/api-docs-restructure

Conversation

@selmanozleyen

@selmanozleyen selmanozleyen commented Sep 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

4th step of #1279
@selmanozleyen selmanozleyen mentioned this pull request Sep 3, 2026
Open
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from 7b33737 to 46f2d77 Compare September 25, 2026 10:41
@codecov

codecov Bot commented Sep 25, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (feat/enum-to-literal@1dc3a62). Learn more about missing BASE report.

Additional details and impacted files 
@@                   Coverage Diff                   @@
##             feat/enum-to-literal    #1287   +/-   ##
=======================================================
  Coverage                        ?   79.18%           
=======================================================
  Files                           ?       65           
  Lines                           ?     9545           
  Branches                        ?     1584           
=======================================================
  Hits                            ?     7558           
  Misses                          ?     1455           
  Partials                        ?      532
Files with missing lines Coverage Δ
src/squidpy/_docs.py 95.45% <ø> (ø)
...uidpy/experimental/im/_calculate_image_features.py 89.42% <ø> (ø)
src/squidpy/experimental/im/_qc_image.py 85.39% <ø> (ø)
src/squidpy/experimental/im/_stain/_normalize.py 94.82% <ø> (ø)
src/squidpy/experimental/im/_stain/_reference.py 84.93% <ø> (ø)
src/squidpy/experimental/im/_utils.py 67.26% <ø> (ø)
src/squidpy/experimental/pl/_qc_image.py 60.91% <ø> (ø)
src/squidpy/experimental/pl/_tiling_qc.py 64.70% <ø> (ø)
src/squidpy/experimental/tl/_stitched_labels.py 84.57% <ø> (ø)
src/squidpy/experimental/tl/_tiling_qc.py 69.76% <ø> (ø)
... and 4 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
@selmanozleyen

selmanozleyen commented Sep 25, 2026

Copy link
Copy Markdown
Member Author

so I talked with @timtreis and we pointed out a +/- expanding bug. Plus maybe adding these rules about Params, Fits and Results into a contribution guideline.
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from 46f2d77 to d594650 Compare September 25, 2026 12:48
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch 2 times, most recently from 11d8760 to e5f0d6b Compare September 25, 2026 19:42
@selmanozleyen
selmanozleyen removed this pull request from stack #1281 September 25, 2026 20:17
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from e5f0d6b to b1543f0 Compare September 25, 2026 20:18
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from b1543f0 to fb15c70 Compare September 25, 2026 20:22
@selmanozleyen
selmanozleyen force-pushed the feat/enum-to-literal branch 2 times, most recently from 60b8138 to ec2d430 Compare September 25, 2026 21:58
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from fb15c70 to 8bad4bb Compare September 25, 2026 21:58
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from 8bad4bb to 4953fca Compare September 25, 2026 22:04
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from 4953fca to 3776c9f Compare September 25, 2026 22:28
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from 3776c9f to 7d690db Compare September 29, 2026 14:58
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from 7d690db to 0aa74a8 Compare September 29, 2026 16:05
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from 0aa74a8 to 67fdfd1 Compare October 1, 2026 12:15
@selmanozleyen
group api by module and kind
2e59d4b 
The API page was one flat list per area, every line repeating the module it belonged to,
and `experimental` was a single block interleaving `im`, `tl` and `pl`. Group it: every
section names its module, `experimental` splits by submodule and then by what the entries
are for, and `neighbors` moves under Graph so `GraphMatrixT` is documented once rather than
beside the `gr` functions, where a bare type variable read as public API.

`squidpy.types` gains the two result tuples alongside the parameter bags, and the params
leave `im`/`tl`'s `__all__` so it is the single public route to them.

Nine names were public but absent from the page, among them `detect_tissue`, `make_tiles`
and `qc_image`.

Docs machinery, so the above renders: attributes inline with their types rather than an
untyped summary table, `navigation_depth` at 5 so a section unfolds to its pages instead of
stopping at the sub-section, and page titles as the bare name rather than the dotted path
repeated in every nav entry. `typeddict.rst` goes: it was byte-identical to the built-in
`base.rst` it shadowed, so it rendered nothing the default did not.
@selmanozleyen
Stack parameters like scanpy
a2721fe 
The Python domain renders a typed field inline as ``name (type) - description``
inside a two-column grid, so the three things a reader scans for share one
run-on line indented behind the "Parameters:" label.

A doctree transform splits each entry into ``name : type`` and its prose, and
the field list is laid out as blocks rather than a grid. ``typehints_defaults``
puts each default next to its type. The signature line gets the name at a size
worth landing on, with the module path receding behind it.
@selmanozleyen
Fill docstring gaps and trim
4b098a6 
``pl.qc_image`` respelled every type the annotation already gives and named its
return twice; ``tl.make_stitched_labels`` and ``pl.tiling_qc`` documented no return
at all. Each parameter now renders its own ``(default: x)``, so the inline
``(default)`` markers duplicate it -- the computed ones, which no signature can
show, stay. ``QCMetric`` is a fifteen-value alias that ``qc_image`` spelled out
twice; it renders by name.
@selmanozleyen
Drop StitchParams from the api docs
88203f3
@selmanozleyen
Drop toc_object_entries: the per-class pages keep params keys out of …
d100b90 
…the nav
@selmanozleyen
Drop the double dashes from comments and docstrings
8c3f9ad
@selmanozleyen
Parametrize the params tests over the params types only
575e016
@selmanozleyen
One import path for the params, restore the qc_table_key fallback in …
a419f36 
…the docs
@selmanozleyen
Hide the dict API in one place, inline the single-use default lookup
6393fa0
@selmanozleyen
selmanozleyen force-pushed the feat/api-docs-restructure branch from 67fdfd1 to 6393fa0 Compare October 1, 2026 12:22

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant

@selmanozleyen