AnswerDotAI / AnswerDotAI/fastcore

Be able to translate docment to numpy docstring

Open
#493 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Jupyter Notebook
Stars
1.1k
Forks
295
Avg merge
1d 6h
Merged PRs (30d)
7

Description

I don't know whether to create this issue here or in the `nbdev` repo. As an enhancement proposal, it would be great to be able to generate .py modules with numpy docstrings, from the original notebooks that have docments, and then convert back if someone edits the docstring in the .py module, something like:

Original notebook:
```python
def add (x: int, # First summand.
y: int, # Second summand.
): int # Result of adding `x` and `y`.
"Adds x and y"
return a+b
```
Generated .py module:
```python
def add (x: int,
y: int,
): int
"""
Adds x and y.

Parameters
----------
x: int
First summand.
y: int
Second summand.
Returns
-------
int
Result of adding `x` and `y`.
"""
return a+b
```

We modify the docstring in the .py module:
```python
def add (x: int,
y: int,
): int
"""
Adds integer x and integer y.

Parameters
----------
x: int
First number to add.
y: int
Second number to add.
Returns
-------
int
Result of adding `x` and `y`.
"""
return a+b
```

Convert back to notebook with docment syntax:
```python
def add (x: int, # First number to add.
y: int, # Second number to add.
): int # Result of adding `x` and `y`.
"Adds integer x and integer y."
return a+b
```
It seems this is not difficult to do with the current functionality, is this something that would be interesting for the team?
Thank you very much for your awesome work.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing docment generation and conversion functionality and the related nbdev repository, as suggested in the issue. Compare the notebook examples with the requested NumPy docstring output and round-trip editing behavior; done means documentation can be converted in both directions while preserving the descriptions.

Written by the indexing model from the issue text.

Assessment

Tech stack
jupyter-notebook, python
Domain
developer-experience, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.