AnswerDotAI / AnswerDotAI/nbdev
How to document a module and or constants?
- Dominant language
- Jupyter Notebook
- Stars
- 5.3k
- Forks
- 513
- Avg merge
- 2d 30m
- Merged PRs (30d)
- 8
Description
Let's say I have a notebook `00_cons.ipynb` Which contains some constants (maybe some compiled regex expressions, or maybe just some default values)
# Example Notebook `00_cons.ipynb`
## Constants
> constants for my package
```python
#| default_exp cons
```
```python
#| hide
from nbdev.showdoc import *
```
### Named Literals
```python
#| export
ASTERICK = '*'
```
```python
# default values, string-ly typed options, etc
# ...
```
### Meta-Data Keys
```python
#| export
OBS = 'obs'
VAR = 'var'
```
### Regex Expressions
> some precompiled regex expressions
```python
#| export
import re
```
```python
#| export
WORDS_TO_SNAKE_WITH_UPPERCASE = re.compile(
r'[A-Z]?[a-z]+' # A possible uppercase followed by lowercase letters
r'|[A-Z]{2,}(?=[A-Z][a-z]|\d|\W|$)' # Two or more consecutive uppercase letters
r'|\d+' # One or more digits
r'|[A-Z]{2,}' # Two or more consecutive uppercase letters
r'|[A-Z]$' # Uppercase letter at end of string
)
```
```python
#| hide
import nbdev; nbdev.nbdev_export()
```
# Problem Statement
Above doesn't really generate any documentation
Now we could add an `00__init__.ipynb` file with a `#| default_exp cons.__init__`
to try and get around this.
```python
#| hide
from types import ModuleType
def is_dunder(s: str) -> bool:
return s.startswith('__') and s.endswith('__')
def drop_dunders(m: ModuleType) -> list:
return list(filter(lambda s: not is_dunder(s), dir(m)))
def cons_dict(m: ModuleType) -> dict:
return dict(zip(m.__all__, list(map(lambda a: getattr(m, a), m.__all__))))
from mypkg import cons
show_doc(cons)
show_doc(drop_dunders(cons))
show_doc(cons_dict(cons))
```
None of these work well.
```python
CONST: str = 'A_CONSTANT''''
This is my constant
Parameters
----------
Here is a note
'''
show_doc(CONST)
```
Will yield
```
A_CONSTANT
This is my constant
Parameters
Here is a note
A_CONSTANT This is my constant
```
See #1313 . As `show_doc` doesn't work with `Notes`, etc
Contributor guide
Research direction
Start with 00_cons.ipynb and the attempted 00__init__.ipynb, then inspect the show_doc examples and nbdev.nbdev_export call. Compare the current output for module constants with the concern in #1313; done means constants and their notes render as usable documentation without the demonstrated duplication.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter-notebook, python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100