Improve examples in docstrings
Dieses Issue hat noch niemand übernommen.
- Vorherrschende Sprache
- Jupyter Notebook
- Sterne
- 853
- Forks
- 322
- PR-Merge-Kennzahlen
- Keine gemergten PRs in 30 T.
Beschreibung
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.
Beitragsleitfaden
Für dieses Repository ist kein Beitragsleitfaden indexiert
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Öffne einen Pull Request, der die Issue-Nummer nennt.
Rechercherichtung
Beginne mit der Prüfung von Pull Request #433 und der vorhandenen docstrings, die darin behandelt werden. Identifiziere Beispiele, die sample-data verwenden oder das angegebenen NumPy-style-doctest-Format nicht einhalten; fertig ist die Aufgabe, wenn die ausgewählten Beispiele funktionieren, nach Möglichkeit eigenständig sind, gegebenenfalls veröffentlichte PhysioNet-Daten verwenden und einem einheitlichen Stil folgen.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- python
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Aktivitätsstatus
- Veraltet
- Klarheit
- Muss geklärt werden
- Anfängerfreundlichkeit
- 42/100