Populate API Reference landing page #381
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR updates the docstrings across multiple modules to address rendering issues in the API reference landing page. The changes complete truncated text in the "datasets", "simulators", and "experimental" modules, and provide clearer descriptions for the packages.
Reviewed Changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| bayesflow/workflows/init.py | Added docstring for the BasicWorkflow interface |
| bayesflow/utils/init.py | Introduced a module-level docstring for utility functions |
| bayesflow/types/init.py | Updated docstring to clarify type usage for annotations |
| bayesflow/simulators/init.py | Expanded docstring to include missing text about the Simulator |
| bayesflow/networks/init.py | Added improved description for neural network architectures |
| bayesflow/metrics/init.py | Updated metric module docstring with clearer guidelines |
| bayesflow/experimental/init.py | Fixed missing “Proceed with caution.” in the experimental modules |
| bayesflow/distributions/init.py | Corrected and completed the distribution module docstring |
| bayesflow/diagnostics/init.py | Refined docs for plotting and metric utilities |
| bayesflow/datasets/init.py | Updated dataset module docstring to include complete text |
| bayesflow/approximators/init.py | Added comprehensive description for approximator components |
| bayesflow/adapters/init.py | Included clear narrative for adapter transforms detailing usage |
Comments suppressed due to low confidence (2)
bayesflow/networks/init.py:2
- [nitpick] The escaped 's' in this docstring appears unusual; please verify whether the backslash is necessary for correct rendering of the trailing 's' or if it can be removed.
A rich collection of neural network architectures for use in :py:class:`~bayesflow.approximators.Approximator`\ s.
bayesflow/metrics/init.py:2
- [nitpick] The backslash before the trailing 's' in this link text seems atypical; please check if it's required for correct docstring formatting or if it should be omitted.
A collection of `keras.Metric <https://keras.io/api/metrics/base_metric/#metric-class>`__\ s for evaluating the
Codecov ReportAll modified and coverable lines are covered by tests ✅
|
vpratz
left a comment
vpratz
left a comment
There was a problem hiding this comment.
Looks good to me, thanks for writing them :)
|
@vpratz Do you know why some of the text does not render correctly? I have tried searching for a solution to this but have not come up with anything. See the original post for examples. |
|
Sorry, I missed the original post, I'll take a look. |
|
So, the missing part is due to Sphinx autosummary only displaying what it considers the first sentence, so up to the first period (excluding special ones like those in brackets, classnames etc). I'll search if there are options in to adapt this behavior. |
|
From my first impression, it does not seem configurable. I think our main options are:
What do you think is best here? Or do you have other ideas? |
|
@vpratz Thank you for the research. I'll improve the first sentence of the docs. |
|
Looks good to me, thanks for the changes :) |
Some docstrings don't yet render correctly:
We could also try to improve the links to
kerasclasses with intersphinx.