docs: Build official documentation site#123
Conversation
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
KenyaOtsuka
left a comment
There was a problem hiding this comment.
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.
| ... dirs_pattern=['layer', 'subject', 'roi'], | ||
| ... file_pattern='<image>.mat', | ||
| ... variable='feat') | ||
| >>> data = ds.get(layer='conv1', subject='TH', roi='VC', image='Image_001') |
There was a problem hiding this comment.
I think TH should be replaced with something like sub-01.
| 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 |
There was a problem hiding this comment.
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
This reverts commit d4fe070.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… 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>
|
Thank you for the thorough review! I've addressed all the points you raised:
Regarding |
Coverage Report
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
KenyaOtsuka
left a comment
There was a problem hiding this comment.
I confirmed that all griffe warnings have been resolved.
This looks good to me!
|
Hey @ganow, sorry, I'm getting to this so late. Should I still have a look at the docs even though the |
|
@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. |
|
Hey @ganow, no worries or problems at all. I'm very sorry for not responding in a timely manner. |
Summary
Refs #122.
This PR sets up the initial official documentation foundation for bdpy using MkDocs, Material for MkDocs, and mkdocstrings.
It includes:
CONTRIBUTING.mdThe 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:
Then open:
For a one-shot build check:
mkdocs build --strictis 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: