refactor: restructure the api docs (4/4) - #1287
Draft
selmanozleyen wants to merge 3 commits into
Draft
Conversation
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.
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.
``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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
4th step of #1279