Improve examples in docstrings
Nessuno ha ancora preso questa issue.
- Lingua principale
- Jupyter Notebook
- Stelle
- 853
- Fork
- 322
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Descrizione
Pull request #433 brings to mind some things that could be improved in docstrings more generally. Cleaning these up might be a good starter issue.
-
Obviously, code examples should be correct and actually work. :)
-
Code examples should also be self-contained if possible, and avoid referring to files in
sample-data(most people reading the documentation are probably not running the code directly from the git repository.) In most cases, it's better to use examples from published databases on PhysioNet. -
Code examples should be written in a consistent style. We generally use numpy style (https://numpydoc.readthedocs.io/en/latest/format.html) for docstrings, but we haven't been entirely consistent. In particular, numpy style requires examples to be written in "doctest" style, like this:
"""
Examples
--------
>>> np.add([[1, 2], [3, 4]],
... [[5, 6], [7, 8]])
array([[ 6, 8],
[10, 12]])
"""
This format has some nice properties (it can be tested automatically by doctest, and formatted nicely by sphinx.) On the other hand, the "..." is a little annoying when you want to copy and paste an example.
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Inizia esaminando la pull request #433 e i docstring esistenti di cui tratta. Individua gli esempi che usano sample-data o che non seguono il formato doctest NumPy indicato; il lavoro è completo quando gli esempi selezionati funzionano, sono autonomi ove possibile, usano dati pubblicati di PhysioNet quando appropriato e seguono uno stile coerente.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Ferma
- Chiarezza
- Da chiarire
- Idoneità per principianti
- 42/100