Skip to content

docs: Build official documentation site#123

Merged
KenyaOtsuka merged 25 commits into
devfrom
docs/site-setup
May 26, 2026
Merged

docs: Build official documentation site#123
KenyaOtsuka merged 25 commits into
devfrom
docs/site-setup

Conversation

@ganow
Copy link
Copy Markdown
Contributor

@ganow ganow commented May 21, 2026

Summary

Refs #122.

This PR sets up the initial official documentation foundation for bdpy using MkDocs, Material for MkDocs, and mkdocstrings.

It includes:

  • MkDocs site configuration and documentation dependency setup
  • API reference pages generated mechanically with mkdocstrings from NumPy-style docstrings
  • Hierarchical documentation pages for a small set of frequently referenced API modules
  • A provisional getting started page, which is still mostly boilerplate and needs refinement
  • Contributor-facing documentation in CONTRIBUTING.md
  • Removal of the previous mostly-empty Jekyll docs setup

The API reference is the most complete part of this initial PR. Non-API pages are still generally sparse and should be expanded in follow-up work.

Behavior

This PR is intended to be documentation-only from a user-facing behavior perspective.

The Python source edits are limited to docstring/rendering cleanup and documentation support so that mkdocstrings can parse and display the API reference correctly. No runtime behavior changes are intended.

Local preview

Install the docs dependency group and run the MkDocs development server:

uv run --group docs mkdocs serve

Then open:

http://127.0.0.1:8000/

For a one-shot build check:

uv run --group docs mkdocs build

mkdocs build --strict is not clean yet because existing docstrings still produce griffe warnings. The non-strict build succeeds.

Notes

I have created a draft version of the bdpy documentation. I would appreciate it if you could check the documentation in your local environment.

Currently, I feel that various information is lacking for general package documentation, such as the Getting Started page (which is currently just a mockup written for the time being), as well as other user guides and tutorials.

Therefore, I believe we need to enrich the documentation by following one of these two approaches:

  1. Create a topic branch before merging this PR, and then merge that topic branch into this branch.
  2. Merge this PR into main, and then merge subsequent topic branches into main asynchronously.

ganow and others added 20 commits May 21, 2026 18:12
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Resolve symbol duplication, private method leakage, and section-style
issues in the auto-generated API reference.

- Add missing mkdocstrings handler options: docstring_section_style=list,
  merge_init_into_class, separate_signature, show_root_heading,
  show_symbol_type_heading, filters=["!^_"], and others
- Drop global show_submodules to eliminate double-rendering of re-exported
  symbols (e.g. DataStore appeared twice under dataform)
- Restructure stubs for packages with empty __init__.py (dl, evals, recon,
  opendata, dataset, pipeline, task) to target submodules directly,
  avoiding bdpy.recon.torch.__init__'s bare `import torch` pulling in
  the entire PyTorch namespace

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- bdata.py: retrun_index -> return_index (3 occurrences in BData.select)
- utils.py: successsive -> successive (vstack, concat_dataset)
- icnn.py: loss_function -> loss_func, display_interval -> disp_interval
- preproc/interface.py: Mode/Baseline/ZeroThreshold -> mode/baseline/zero_threshold

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
numpydoc requires a blank line before each section header (Parameters,
Returns, etc.) to recognize it as a section. Without it the entire
docstring collapses to a prose paragraph in the API reference.

- ml/learning.py: Classification class
- fig/makeplots.py: Parameters and Returns sections
- fig/makeplots2.py: Parameters and Returns sections

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
In BData's class docstring, a prose sentence was placed between the
Parameters and Attributes sections, causing the numpydoc parser to
generate phantom parameter rows in the API reference.

Moved to a Notes section, which is the standard numpy docstring
convention for supplementary information.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
corrcoef and corrmat had Returns entries without type annotations
(e.g. bare 'r' instead of 'r : numpy.ndarray'), causing mkdocstrings
to display the variable name in the Type column instead of the actual type.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Examples sections were written as plain indented text, causing
mkdocstrings to render code as prose paragraphs. Prose text interspersed
with code also triggered phantom headings via the markdown setext-heading
pattern.

- dataform/datastore.py: DataStore and DirStore.get examples
- preproc/interface.py: shift_sample example (also fixes commented-out output)
- fig/tile_images.py: all four layout diagram examples

Also renames 'Example' headers to 'Examples' (numpy standard).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- bdata/bdata.py: removed hand-maintained "API list" section with setext
  underline, which was being rendered as an H2 heading in the API reference
- stats/__init__.py: removed redundant "Functions:" bullet list that
  duplicates what mkdocstrings generates automatically

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- recon/torch/icnn.py: fix typos numpy.ndarar/ndarary -> numpy.ndarray,
  remove (default: ...) suffix from type specs, fix crop_generator_output
  parameter name that had assignment syntax mixed in
- ml/crossvalidation.py: fix unclosed parenthesis in array-like shape
  annotation (2 occurrences)
- stats/corr.py: use numpy-standard {'row', 'col'} set notation instead
  of prose "str, 'row' or 'col'" (2 occurrences)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Packages whose __init__.py re-exports symbols via aliases are not
rendered by mkdocstrings when show_submodules is off. Fix by pointing
each ::: directive at the canonical submodule (e.g. bdpy.bdata.bdata)
rather than the package root (bdpy.bdata), for bdata, stats, feature,
util, mri, distcomp, dl, and recon.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- remove_nan_value: convert from non-numpy docstring format to numpy style
  Parameters/Returns sections
- ImageDataset (__init__): add summary line so merge_init_into_class
  correctly renders the Parameters section
- BaseCallback: wrap inline doctest example in a fenced code block to
  prevent >>> from being interpreted as markdown blockquotes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace show_submodules:false + per-submodule ::: directives with
show_submodules:true + single ::: bdpy.<pkg> per page. This prevents
missing-module gaps when new submodules are added without updating
the stubs. Previously absent modules (dl.torch.dataset, dl.torch.models,
dl.torch.domain.feature_domain, dataform.utils, fig.makeplots family,
ml.learning, ml.crossvalidation, ml.model, preproc.preprocessor) now
appear automatically.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Split bdata, dl, ml, and recon API docs into submodule pages

- Add overview pages for nested API reference sections

- Update API index and MkDocs nav to point to the new structure

- Adjust mkdocstrings options to reduce duplicate headings and submodule output
@ganow ganow requested review from KenyaOtsuka and PeerHerholz May 21, 2026 13:40
@ganow ganow mentioned this pull request May 22, 2026
@ganow ganow marked this pull request as ready for review May 26, 2026 04:54
@ganow ganow changed the title WIP: Build official documentation site docs: Build official documentation site May 26, 2026
@ganow ganow changed the base branch from main to dev May 26, 2026 07:00
Copy link
Copy Markdown

@KenyaOtsuka KenyaOtsuka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for this great update!

Overall, I think this looks good as a foundation version of the BdPy documentation. The API reference structure looks reasonable to me, and I think it is fine that the non-API pages are still sparse at this stage, since they can be improved in follow-up PRs.

I left a few comments. I would appreciate it if you could take a look.

One additional point:
I noticed that docs/bdata_api_examples.md and docs/dataform_features.md are removed in this PR.

For docs/bdata_api_examples.md, most of the basic BData examples seem to be covered by the new Getting Started page, so I think its removal is probably fine.

However, I could not find equivalent replacement content for docs/dataform_features.md. If this content was removed mainly because it does not fit the new MkDocs structure, I think it would be a bit unfortunate to lose it entirely. It may be better to keep it somewhere.

Comment thread bdpy/dataform/datastore.py Outdated
... dirs_pattern=['layer', 'subject', 'roi'],
... file_pattern='<image>.mat',
... variable='feat')
>>> data = ds.get(layer='conv1', subject='TH', roi='VC', image='Image_001')
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think TH should be replaced with something like sub-01.

Comment thread bdpy/ml/crossvalidation.py Outdated
group : array-like (shape = (n_samples, )
group : array-like of shape (n_samples,)
Group labels (e.g., run labels, block labels, ...)
n_folds : int, optional
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be nfolds

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found a few other warnings that appear to be caused by simple docstring/signature mismatches. I think these should be easy to fix, so it would be good to address them in this PR.

WARNING -  griffe: bdpy/mri/roi.py:159: Parameter 'roi_mask' does not appear in the function signature
WARNING -  griffe: bdpy/bdata/bdata.py:288: Parameter 'key' does not appear in the function signature
WARNING -  griffe: bdpy/ml/learning.py:183: No types or annotations for parameters ['None']
WARNING -  griffe: bdpy/ml/learning.py:183: Parameter 'None' does not appear in the function signature

ganow and others added 2 commits May 26, 2026 17:12
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
ganow and others added 3 commits May 26, 2026 17:16
… and nav

- datastore.py: replace subject='TH' with 'sub-01' in example
- crossvalidation.py: rename n_folds -> nfolds in docstring to match signature
- roi.py: rename roi_mask -> label in add_roilabel docstring
- bdata.py: rename key -> metakey in edit_metadatadescription docstring
- learning.py: remove spurious Parameters/None section from CrossValidation.run
- mkdocs.yml: add Features and DecodedFeatures page to nav

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ganow
Copy link
Copy Markdown
Contributor Author

ganow commented May 26, 2026

Thank you for the thorough review!

I've addressed all the points you raised:

  • subject='TH' → replaced with 'sub-01' in datastore.py
  • n_foldsnfolds in crossvalidation.py
  • griffe warnings (roi.py, bdata.py, learning.py) — all four parameter/signature mismatches fixed

Regarding dataform_features.md: I reverted the deletion commit and re-deleted only _config.yml and bdata_api_examples.md. dataform_features.md is now kept as a non-API page and added to the site navigation under "Features and DecodedFeatures".

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 26, 2026

Coverage

Coverage Report
FileStmtsMissCoverMissing
bdpy/bdata
   bdata.py39919551%62, 87, 92, 96, 101, 105, 115–117, 173, 216–222, 235–245, 259–260, 293, 297, 301–339, 388–394, 402–403, 408–409, 426–433, 451–452, 458, 491, 522, 531, 543, 572–581, 593, 608, 644, 666–674, 679–712, 721, 733–740, 744–750, 754–782, 786–807, 811–845, 849–851, 855–857, 861–870
   featureselector.py641281%62–67, 69–74
   metadata.py67199%84
   utils.py1133767%71, 82, 85–86, 95, 127–173, 201, 246, 258, 263
bdpy/dataform
   datastore.py1078521%60–76, 91–94, 98–99, 103–114, 117–120, 123–128, 132–133, 138–159, 191–198, 219–256, 259–262
   features.py29816545%31–32, 43–46, 90–92, 101–103, 107, 111, 115, 119, 152–153, 157–161, 168–197, 214–215, 224–225, 232–236, 274, 288, 305–319, 323, 327, 331, 335, 339, 343, 347, 351, 355, 359, 364–394, 398–418, 422–462, 465, 470–477, 491–493, 496–499, 502–505, 508–512, 515–516, 536–549
   kvs.py1771393%21, 24, 114, 118, 127–131, 171, 173, 185, 254, 282
   pd.py9544%25–27, 43–44
   sparse.py67790%29, 52–58, 74, 109, 123
   utils.py12120%3–18
bdpy/dataset
   utils.py45450%3–98
bdpy/distcomp
   distcomp.py921880%33, 35, 49, 53, 55, 66–70, 74, 76, 81–82, 89–93, 97
bdpy/dl
   caffe.py60600%4–129
bdpy/dl/torch
   base.py432444%31–41, 48, 54, 60, 63, 73–83, 90, 96, 102, 105
   dataset.py744046%37–39, 67–72, 75, 78–88, 122–130, 133, 136–149, 196, 199
   models.py33322632%148–169, 297–316, 327–331, 345–350, 442–494, 515–517, 528–587, 611–614, 625–684, 708–711, 722–771, 790–793, 804–853, 872–875
   torch.py1215555%189–226, 229, 232–244, 247–282
bdpy/dl/torch/domain
   core.py46296%47, 63
   feature_domain.py24196%30
   image_domain.py81396%91, 94, 257
bdpy/evals
   metrics.py954553%49–53, 82–112, 130–142, 151–152, 157, 184–191
bdpy/feature
   feature.py30293%69–70
bdpy/fig
   __init__.py550%6–10
   draw_group_image_set.py90900%3–182
   fig.py88880%16–164
   makeplots2.py2632630%1–610
   makeplots.py3363360%1–731
   tile_images.py59590%1–187
bdpy/ml
   crossvalidation.py592754%47–48, 113–114, 117–118, 138, 164–196
   learning.py3139769%9, 47–48, 52, 56, 63, 96–109, 114–130, 133, 163–175, 185–210, 294, 310, 314–316, 319–320, 330, 340–341, 346–347, 357–365, 368–369, 377, 412–419, 440, 453, 461, 470, 502–504, 543, 556, 559, 568, 577, 582, 603
   model.py14012014%29–39, 54–70, 86–144, 156–169, 184–222, 225, 230–250, 254–258, 271–285
   searchlight.py161319%32–51
bdpy/mri
   fmriprep.py4974519%25–34, 38, 44–62, 65–75, 78–89, 92–160, 163–194, 230–360, 367–380, 384, 388–390, 394, 398–400, 410–434, 437–454, 457–464, 471–472, 475–491, 494, 498, 502–815, 819–831, 842–862
   glm.py403610%46–95
   image.py241921%29–54
   load_epi.py281836%36–50, 56–63, 82–88
   load_mri.py191616%16–36
   roi.py24821712%37–100, 165–235, 241–314, 320–387, 399–466, 473–499
   spm.py15813912%26–155, 162–166, 170, 174–179, 183–300
bdpy/opendata
   __init__.py110%1
   openneuro.py2102100%1–329
bdpy/pipeline
   config.py36294%37–38
bdpy/preproc
   interface.py521669%111–123, 148–157
   preprocessor.py1296947%35, 44, 112–114, 121–128, 138–189, 196–227
   select_top.py23196%55
bdpy/recon
   utils.py55550%4–146
bdpy/recon/torch
   icnn.py1611610%15–480
bdpy/recon/torch/modules
   critic.py44295%58, 132
   encoder.py29197%29
   generator.py72593%47, 52, 68, 128, 309
   latent.py34391%16, 21, 32
bdpy/recon/torch/task
   inversion.py831187%22, 40, 45, 50, 57, 62, 67, 72, 96, 210, 225
bdpy/stats
   corr.py43393%57, 68, 102
bdpy/task
   callback.py71494%114, 163, 168, 236
   core.py16194%50
bdpy/util
   info.py473623%19–79
   utils.py36878%60, 116–121, 140–142
TOTAL5981363639% 

Tests Skipped Failures Errors Time
218 0 💤 1 ❌ 0 🔥 16.794s ⏱️

@github-actions
Copy link
Copy Markdown

Coverage

Coverage Report
FileStmtsMissCoverMissing
bdpy/bdata
   bdata.py39919551%62, 87, 92, 96, 101, 105, 115–117, 173, 216–222, 235–245, 259–260, 293, 297, 301–339, 388–394, 402–403, 408–409, 426–433, 451–452, 458, 491, 522, 531, 543, 572–581, 593, 608, 644, 666–674, 679–712, 721, 733–740, 744–750, 754–782, 786–807, 811–845, 849–851, 855–857, 861–870
   featureselector.py641281%62–67, 69–74
   metadata.py67199%84
   utils.py1133767%71, 82, 85–86, 95, 127–173, 201, 246, 258, 263
bdpy/dataform
   datastore.py1078521%60–76, 91–94, 98–99, 103–114, 117–120, 123–128, 132–133, 138–159, 191–198, 219–256, 259–262
   features.py29816545%31–32, 43–46, 90–92, 101–103, 107, 111, 115, 119, 152–153, 157–161, 168–197, 214–215, 224–225, 232–236, 274, 288, 305–319, 323, 327, 331, 335, 339, 343, 347, 351, 355, 359, 364–394, 398–418, 422–462, 465, 470–477, 491–493, 496–499, 502–505, 508–512, 515–516, 536–549
   kvs.py1771393%21, 24, 114, 118, 127–131, 171, 173, 185, 254, 282
   pd.py9544%25–27, 43–44
   sparse.py67790%29, 52–58, 74, 109, 123
   utils.py12120%3–18
bdpy/dataset
   utils.py45450%3–98
bdpy/distcomp
   distcomp.py921880%33, 35, 49, 53, 55, 66–70, 74, 76, 81–82, 89–93, 97
bdpy/dl
   caffe.py60600%4–129
bdpy/dl/torch
   base.py432444%31–41, 48, 54, 60, 63, 73–83, 90, 96, 102, 105
   dataset.py744046%37–39, 67–72, 75, 78–88, 122–130, 133, 136–149, 196, 199
   models.py33322632%148–169, 297–316, 327–331, 345–350, 442–494, 515–517, 528–587, 611–614, 625–684, 708–711, 722–771, 790–793, 804–853, 872–875
   torch.py1215555%189–226, 229, 232–244, 247–282
bdpy/dl/torch/domain
   core.py46296%47, 63
   feature_domain.py24196%30
   image_domain.py81396%91, 94, 257
bdpy/evals
   metrics.py954553%49–53, 82–112, 130–142, 151–152, 157, 184–191
bdpy/feature
   feature.py30293%69–70
bdpy/fig
   __init__.py550%6–10
   draw_group_image_set.py90900%3–182
   fig.py88880%16–164
   makeplots2.py2632630%1–610
   makeplots.py3363360%1–731
   tile_images.py59590%1–187
bdpy/ml
   crossvalidation.py592754%47–48, 113–114, 117–118, 138, 164–196
   learning.py3159769%9, 47–48, 52, 56, 63, 96–109, 114–130, 133, 163–175, 185–210, 294, 310, 314–316, 319–320, 330, 340–341, 346–347, 357–365, 368–369, 377, 412–419, 440, 453, 461, 470, 502–504, 543, 556, 559, 568, 577, 582, 603
   model.py14012014%29–39, 54–70, 86–144, 156–169, 184–222, 225, 230–250, 254–258, 271–285
   searchlight.py161319%32–51
bdpy/mri
   fmriprep.py4974519%25–34, 38, 44–62, 65–75, 78–89, 92–160, 163–194, 230–360, 367–380, 384, 388–390, 394, 398–400, 410–434, 437–454, 457–464, 471–472, 475–491, 494, 498, 502–815, 819–831, 842–862
   glm.py403610%46–95
   image.py241921%29–54
   load_epi.py281836%36–50, 56–63, 82–88
   load_mri.py191616%16–36
   roi.py24821712%37–100, 165–235, 241–314, 320–387, 399–466, 473–499
   spm.py15813912%26–155, 162–166, 170, 174–179, 183–300
bdpy/opendata
   __init__.py110%1
   openneuro.py2102100%1–329
bdpy/pipeline
   config.py36294%37–38
bdpy/preproc
   interface.py521669%111–123, 148–157
   preprocessor.py1296947%35, 44, 112–114, 121–128, 138–189, 196–227
   select_top.py23196%55
bdpy/recon
   utils.py55550%4–146
bdpy/recon/torch
   icnn.py1611610%15–480
bdpy/recon/torch/modules
   critic.py44295%58, 132
   encoder.py29197%29
   generator.py72593%47, 52, 68, 128, 309
   latent.py34391%16, 21, 32
   optimizer.py22959%8–26
bdpy/recon/torch/task
   inversion.py881583%11–16, 22, 40, 45, 50, 57, 62, 67, 72, 96, 210, 225
bdpy/stats
   corr.py43393%57, 68, 102
bdpy/task
   callback.py71494%114, 163, 168, 236
   core.py16194%50
bdpy/util
   info.py473623%19–79
   utils.py36878%60, 116–121, 140–142
TOTAL5998364939% 

Tests Skipped Failures Errors Time
218 0 💤 0 ❌ 0 🔥 16.458s ⏱️

@KenyaOtsuka KenyaOtsuka self-requested a review May 26, 2026 09:40
Copy link
Copy Markdown

@KenyaOtsuka KenyaOtsuka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I confirmed that all griffe warnings have been resolved.
This looks good to me!

@KenyaOtsuka KenyaOtsuka merged commit 89b867c into dev May 26, 2026
3 of 6 checks passed
@ganow ganow deleted the docs/site-setup branch May 26, 2026 09:54
@PeerHerholz
Copy link
Copy Markdown

Hey @ganow,

sorry, I'm getting to this so late. Should I still have a look at the docs even though the PR is already merged?

@ganow
Copy link
Copy Markdown
Contributor Author

ganow commented May 29, 2026

@PeerHerholz Thank you for checking this PR! I apologize for merging it without waiting for your review. If there are any points of concern, I would appreciate your comments. I know you are busy, so please feel free to skip the review if you prefer. I believe this PR has established the foundation for building the official documentation, so I would be very happy if you could cooperate with us in the future regarding documentation creation from the perspective of a new user.

@PeerHerholz
Copy link
Copy Markdown

Hey @ganow,

no worries or problems at all. I'm very sorry for not responding in a timely manner.
Yes, I would definitely like to support this endeavor and assign dedicated time to work and focus on this.

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants