huggingface / huggingface/doc-builder

[autodoc] Parse `PEP 257` style docstring

Open
#410 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
Python
Stars
144
Forks
59
Avg merge
2d 5h
Merged PRs (30d)
13

Description

Copied from https://github.com/rr-/docstring_parser/issues/71#issue-1318744037

> The approved [PEP 257](https://peps.python.org/pep-0257/#what-is-a-docstring) mentions the so-called "attribute docstrings", which are string literals in the line after where an attribute is defined. These kind of docstrings are supported by a several packages, for example sphinx's [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) extension.

An example looks like below:

```python
from dataclasses import dataclass
from typing import Optional
from docstring_parser import parse_from_object

@dataclass
class RewardConfig:
"""
RewardConfig collects all training arguments related to the [`RewardTrainer`] class.
"""

max_length: Optional[int] = None
"""The maximum length of the sequences in the batch. This argument is required if you want to use the default data collator."""
gradient_checkpointing: Optional[bool] = True
"""If True, use gradient checkpointing to save memory at the expense of slower backward pass."""

doc = parse_from_object(RewardConfig)

print(doc.short_description)
print()
for i in doc.params:
print(f"{i.arg_name}, {i.type_name} (default - {i.default})\n {i.description}")
print()
```
```
RewardConfig collects all training arguments related to the [`RewardTrainer`] class.

max_length, Optional[int] (default - None)
The maximum length of the sequences in the batch. This argument is required if you want to use the default data collator.

gradient_checkpointing, Optional[bool] (default - True)
If True, use gradient checkpointing to save memory at the expense of slower backward pass.
```

This appears not supported in the `autodoc` feature of this repo. For example, in TRL our config is https://github.com/huggingface/trl/blob/d608fea0d107d4359f9c03a9d6dd434d292a9f50/trl/trainer/ppo_config.py, but its related docs does not show the documentation.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.