AnswerDotAI / AnswerDotAI/nbdev

How to document a module and or constants?

Open
#1,367 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.