Move dynamic API class constructor docs to class-level docstrings#6273
Move dynamic API class constructor docs to class-level docstrings#6273JanuszL wants to merge 2 commits intoNVIDIA:mainfrom
Conversation
|
!build |
Greptile SummaryThis PR is a pure documentation improvement for the DALI dynamic API module. It follows the numpy docstring convention by relocating constructor parameter documentation from Key changes:
Confidence Score: 5/5Safe to merge — purely documentation restructuring with no functional code changes. All eight changed files contain only docstring edits and Sphinx cross-reference fixes ( No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A["Sphinx autodoc processes class"] --> B{Where is the Parameters section?}
B -->|"Before: __init__ docstring"| C["❌ Parameters hidden\n(autodoc skips __init__ by default)"]
B -->|"After: class-level docstring"| D["✅ Parameters visible in API reference"]
D --> E["cross-references :meth: → :func:"]
E --> F["Correct Sphinx roles for module-level callables"]
Reviews (3): Last reviewed commit: "review fixes" | Re-trigger Greptile |
|
CI MESSAGE: [46787934]: BUILD STARTED |
- Follows the numpy docstring convention by placing Parameters sections in class-level docstrings instead of __init__ docstrings. This ensures Sphinx autodoc renders constructor arguments correctly in the API reference (e.g. Batch arguments were previously not shown) - Replaces :meth: cross-references with :func: for all module-level functions (batch, as_batch, tensor, as_tensor, stream, device, set_current_stream, set_default_stream, get_current_stream, get_default_stream, io.file.read, decoders.image). - Updates: Batch, Tensor, ThreadPool, Stream, Device, EvalContext, RNG Signed-off-by: Janusz Lisiecki <jlisiecki@nvidia.com>
JanuszL
force-pushed
the
dynamic_api_docstrings
branch
from
2dafdb0 to
74c9a86
Compare
|
@greptileai - please re-review |
|
!build |
|
CI MESSAGE: [46789476]: BUILD STARTED |
|
CI MESSAGE: [46789476]: BUILD PASSED |
| This class wraps a CUDA stream object. It can be either a stream created by DALI or a | ||
| compatible object created by a third-party library. | ||
|
|
||
| .. note:: |
There was a problem hiding this comment.
Inconsistency with _batch.py and _tensor.py: those classes use .. warning:: for the "don't construct directly" guidance, but Stream (and Device) use .. note:: here. Stream's phrasing — "Do not construct this class directly" — is actually more imperative than what Batch/Tensor say, so if anything it warrants .. warning:: too. Worth making this consistent across all four classes.
|
|
||
| The device can be either CPU or (specific) GPU. | ||
|
|
||
| .. note:: |
There was a problem hiding this comment.
This was a .. warning:: in the old __init__ docstring and has been downgraded to .. note:: here, while Batch and Tensor keep .. warning:: for the same kind of guidance. Consider keeping .. warning:: for consistency, or align all four classes to .. note:: if the softer tone is intentional.
Signed-off-by: Janusz Lisiecki <jlisiecki@nvidia.com>
|
!build |
|
CI MESSAGE: [47354403]: BUILD STARTED |
|
CI MESSAGE: [47354403]: BUILD PASSED |
4 participants
in class-level docstrings instead of init docstrings. This ensures
Sphinx autodoc renders constructor arguments correctly in the API
reference (e.g. Batch arguments were previously not shown)
functions (batch, as_batch, tensor, as_tensor, stream, device,
set_current_stream, set_default_stream, get_current_stream,
get_default_stream, io.file.read, decoders.image).
Category:
Other (e.g. Documentation, Tests, Configuration)
Description:
in class-level docstrings instead of init docstrings. This ensures
Sphinx autodoc renders constructor arguments correctly in the API
reference (e.g. Batch arguments were previously not shown)
functions (batch, as_batch, tensor, as_tensor, stream, device,
set_current_stream, set_default_stream, get_current_stream,
get_default_stream, io.file.read, decoders.image).
Additional information:
Affected modules and functionalities:
Key points relevant for the review:
Tests:
Checklist
Documentation
DALI team only
Requirements
REQ IDs: N/A
JIRA TASK: DALI-4630