AnswerDotAI / AnswerDotAI/nbdev

How to document a module and or constants?

Aperta
#1,367 1 commento 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
Jupyter Notebook
Stelle
5.3k
Fork
513
Merge medio
2g 30m
PR unite (30g)
8

Descrizione

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

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
jupyter-notebook, python
Ambito
documentation
Tipo di issue
Funzionalità
Difficoltà
4/5
Tempo stimato
3-5 giorni
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.