Mitarbeit an der SciPy-Dokumentation#

Wir freuen uns über Hinweise zu und die Behebung von Dokumentationsfehlern. Um jedoch die größten Probleme anzugehen, müssen wir manchmal einige Fehlerberichte zurückstellen oder übersehen. Hier sind die besten Fehler, die Sie angehen können.

Die höchste Priorität haben **technische Ungenauigkeiten** – ein Docstring, dem ein Parameter fehlt, eine fehlerhafte Beschreibung einer Funktion/eines Parameters/einer Methode und so weiter. Andere „strukturelle“ Fehler wie defekte Links erhalten ebenfalls Priorität. Alle diese Korrekturen sind einfach zu überprüfen und einzufügen. Sie können einen Pull Request (PR) mit der Korrektur einreichen, wenn Sie wissen, wie das geht; andernfalls öffnen Sie bitte ein Issue.

**Tipp- und Rechtschreibfehler** stehen auf einer niedrigeren Stufe; wir freuen uns über Hinweise darauf, können sie aber möglicherweise nicht sofort beheben. Auch diese können als Pull Requests oder Issues behandelt werden.

Offensichtliche **Formulierungsfehler** (wie das Weglassen eines „nicht“) fallen in die Kategorie Tippfehler, aber andere Umformulierungen – selbst grammatikalische – erfordern eine Ermessensentscheidung, was die Hürde erhöht. Man kann sich Fälle vorstellen, in denen nicht klar ist, ob eine „Korrektur“ vorgenommen werden sollte, z. B.

  • Der Versuch, alle Verwendungen (oder Nichtverwendungen) des Oxford-Kommas zu „korrigieren“.

  • Fälle, in denen die Korrektheit des gebräuchlichen Sprachgebrauchs sich entwickelt, z. B. „comprised of“

Die am einfachsten zu akzeptierenden Korrekturen sind diejenigen, bei denen die ursprüngliche Version klar und unzweideutig falsch ist; Änderungen, die eine subtile redaktionelle Beurteilung erfordern, sollten wahrscheinlich vermieden werden. (Beachten Sie jedoch, dass es hierbei nicht darum geht, die Dokumentation zu aktualisieren, um verwirrende Aussagen zu korrigieren oder anderweitig auf Benutzer gemeldete Dokumentationsprobleme zu behandeln.)

Hinweis

Versuchen Sie als allgemeine Richtlinie, kleine Dokumentationsänderungen (wie Tippfehler) anzusammeln, anstatt sie einzeln zu senden. Stellen Sie außerdem sicher, dass Sie, wann immer möglich, die richtigen Befehle verwenden, um CI-Checks zu überspringen für Dokumentationsänderungen.

Einige in C- oder Fortran-Erweiterungsmodulen definierte Funktionen/Objekte haben ihre Docstrings getrennt vom eigentlichen Code definiert. Stellen Sie sicher, dass Sie die gesuchte Funktionsdocstring entweder mit grep oder anderen ähnlichen Werkzeugen suchen.

Lokales Rendern der Dokumentation mit Sphinx#

SciPy-Docstrings werden mit Sphinx und dem PyData Sphinx Theme in HTML gerendert. Das Schreiben von Docstrings wird in den Dokumentationsstil behandelt; dieses Dokument erklärt, wie zu überprüfen ist, ob Docstrings ordnungsgemäß gerendert werden.

Für eine Videoanleitung sehen Sie bitte Rendering SciPy Documentation with Sphinx .

So rendern Sie die Dokumentation auf Ihrem eigenen Rechner

  1. Stellen Sie sicher, dass Sie einen funktionierenden SciPy-Build haben (siehe Aus dem Quellcode kompilieren).

  2. Führen Sie dann python dev.py doc aus, um die Dokumentation zu erstellen. Dies kann beim ersten Mal eine Weile dauern, aber nachfolgende Dokumentations-Builds sind in der Regel viel schneller.

  3. Betrachten Sie die Dokumentation in doc/build/html/. Sie können mit index.html beginnen und stöbern, oder Sie können direkt zu der Datei springen, an der Sie interessiert sind.

Hinweis

  • Änderungen an bestimmten Dokumenten werden beim Neuerstellen der Sphinx-Dokumentation nicht wirksam. In diesem Fall können Sie von Grund auf neu erstellen, indem Sie die Verzeichnisse scipy/doc/build und source/reference/generated löschen oder python dev.py doc clean ausführen und dann die Dokumentation erneut erstellen.

  • Falls die oben genannte Befehlsversion von SciPy von der des neuesten Commits im Repository abweicht, sehen Sie eine Meldung wie diese

    installed scipy 5fd20ec1aa != current repo git version '35fd20ec1a'

    Dies deutet darauf hin, dass Sie wahrscheinlich die falsche SciPy-Installation verwenden. Überprüfen Sie dies mit python -c "import scipy; print(scipy.__file__)".

  • Die SciPy-Dokumentation enthält interaktive Beispiele, die mit Hilfe der Erweiterung jupyterlite-sphinx gerendert werden. Weitere Details finden Sie unter Tutorials als Jupyter-Notebooks hinzufügen oder bearbeiten und Interaktive Beispiele in Docstrings.

Dokumentation in der Cloud prüfen#

Sobald ein PR geöffnet ist, können Sie überprüfen, ob die Dokumentation in der Cloud korrekt gerendert wird.

  1. Melden Sie sich bei GitHub an.

  2. Melden Sie sich bei CircleCI mit Ihrem GitHub-Konto an.

  3. Zurück in GitHub, wählen Sie am unteren Rand des PR „Show all Checks“ (Alle Prüfungen anzeigen).

  4. Wählen Sie neben „Check the rendered docs here!“ (Prüfen Sie die gerenderten Dokumente hier!) „Details“ aus.

Dokumentationsrichtlinien#

Verwenden Sie „muss“, nicht „sollte“#

Wenn eine erforderliche Bedingung für Eingabeparameter angegeben wird, ist das Wort „muss“ dem Wort „sollte“ vorzuziehen. Für viele englischsprachige Sprecher impliziert „muss“ eine stärkere Einschränkung als „sollte“, z. B. „Ich muss Sauerstoff zum Leben haben“ im Gegensatz zu „Ich sollte mehr Sport treiben“.

Ja

Parameters
----------
x : float
    `x` must be nonnegative.

Nein

Parameters
----------
x : float
    `x` should be nonnegative.

Verwendung des ‚versionadded‘-Markup#

  • Für eine neue Funktion gehört das ‚versionadded‘-Markup in den Abschnitt „Notes“ (Hinweise), *nicht* in die Beschreibung am Anfang des Docstrings.

  • Für ein neues Argument, das einer bestehenden Funktion hinzugefügt wird, wird das ‚versionadded‘-Markup am Ende der Beschreibung des Arguments im Abschnitt „Parameters“ (Parameter) platziert.

Zitieren von Wikipedia-Artikeln im Abschnitt „References“ (Referenzen)#

Es ist akzeptabel, Wikipedia-Artikel als Referenzen zu verwenden. Wenn Sie die Zitierung für die Referenz erstellen, geben Sie den Artikeltitel, den Namen „Wikipedia“ (ähnlich wie man einen Journaltitel angibt) und die URL an.

Ja

.. [1] "Zeta Distribution", Wikipedia,
       https://en.wikipedia.org/wiki/Zeta_distribution

Nein

.. [1] https://en.wikipedia.org/wiki/Zeta_distribution

DOIs in Referenzen#

Die Verwendung von DOIs in Referenzen wird dringend empfohlen. Es gibt eine spezielle Sphinx-Syntax für DOIs: :doi:. Zum Beispiel

.. [2] D. Fishkind, S. Adali, H. Patsolic, L. Meng, D. Singh, V. Lyzinski,
       C. Priebe, "Seeded graph matching", Pattern Recognit. 87 (2019):
       203-215, :doi:`10.1016/j.patcog.2018.09.014`

(arXiv-Artikel haben ebenfalls spezielle Markup-Optionen: :arxiv:.)

Aufzählungspunkte#

Dies ist weniger eine Richtlinie als vielmehr eine Erinnerung an das Sphinx-Markup für Aufzählungspunkte. Die falsche Verwendung von Einrückungen ist so häufig, dass es sich lohnt, sie hier zu erwähnen.

Beim Erstellen einer Aufzählung

  • Beenden Sie die vorherige Zeile nicht mit ::.

  • Rücken Sie die Aufzählungspunkte nicht ein.

  • Fügen Sie vor und nach der Liste eine Leerzeile ein.

Einige Beispiele

Ja

Some text that precedes this interesting list:

* The first item in the list.
* The second item in the list.
* You get the idea.

Some text that follows the list.

Nein

Some text that precedes this interesting list:

  * The first item in the list.
  * The second item in the list.
  * You get the idea.

Some text that follows the list.

Nein

Some text that precedes this interesting list:
* The first item in the list.
* The second item in the list.
* You get the idea.
Some text that follows the list.

Eigenständige Beispiele#

Jeder Abschnitt „Example“ (Beispiel) (sowohl in Docstrings als auch in allgemeiner Dokumentation) muss eigenständig sein. Das bedeutet, dass alle Importe explizit sein müssen, die verwendeten Daten definiert sein müssen und der Code funktionieren sollte, wenn er in einen neuen Python-Interpreter kopiert wird.

Ja

>>> import numpy as np
>>> rng = np.random.default_rng()

Nein

>>> rng = np.random.default_rng()

Was möglich (und empfohlen) ist, ist, Codeblöcke mit Erklärungen zu durchsetzen. Leerzeilen müssen jeden Codeblock vom erklärenden Text trennen.

Ja

Some initial text

>>> import numpy as np
>>> rng = np.random.default_rng()

This is some explanation

>>> rng.random(10)

Beispiele und Zufälligkeit#

In der kontinuierlichen Integration (CI) werden Beispiele ausgeführt und die Ausgabe mit den bereitgestellten Referenzen verglichen. Das Hauptziel ist es, sicherzustellen, dass das *Beispiel* korrekt ist; ein Fehler warnt uns, dass das Beispiel möglicherweise angepasst werden muss (z. B. weil sich die API seit seiner Erstellung geändert hat). Doctests sind nicht dazu gedacht, als Unit-Tests der zugrunde liegenden Implementierung verwendet zu werden.

Falls ein Zufallszahlengenerator benötigt wird, muss np.random.Generator verwendet werden. Die kanonische Methode zur Erstellung eines NumPy Generator ist die Verwendung von np.random.default_rng.

Ja

>>> import numpy as np
>>> rng = np.random.default_rng()
>>> sample = rng.random(10)

Ja

>>> import numpy as np
>>> rng = np.random.default_rng(102524723947864966825913730119128190984)
>>> sample = rng.random(10)

Nein

>>> import numpy as np
>>> sample = np.random.random(10)

Das Seeden des Generatorobjekts ist optional. Wenn ein Seed verwendet wird, vermeiden Sie gängige Zahlen und generieren Sie stattdessen einen Seed mit np.random.SeedSequence().entropy. Wenn kein Seed angegeben wird, wird der Standardwert 1638083107694713882823079058616272161 verwendet, wenn Doctests ausgeführt werden. In beiden Fällen werden in der gerenderten Dokumentation keine Seed-Werte angezeigt. Die Absicht ist, Benutzer davon abzuhalten, Seeds in ihren Code zu kopieren und einzufügen, und stattdessen eine explizite Entscheidung über die Verwendung eines Seeds in ihrem Programm zu treffen. Die Konsequenz ist, dass Benutzer die Ergebnisse des Beispiels nicht exakt reproduzieren können, sodass Beispiele mit Zufallsdaten keine präzisen numerischen Werte basierend auf Zufallsdaten referenzieren oder ihren Punkt darauf stützen sollten.

Legacy-Direktive#

Wenn eine Funktion, ein Modul oder eine API im *Legacy*-Modus ist, d. h. sie wird aus Gründen der Abwärtskompatibilität beibehalten, aber für neue Codes nicht empfohlen wird, können Sie die Direktive .. legacy:: verwenden.

Standardmäßig, wenn sie ohne Argumente verwendet wird, generiert die Legacy-Direktive die folgende Ausgabe

Veraltet

Dieses Untermodul gilt als Legacy und wird keine weiteren Updates erhalten. Obwohl wir derzeit keine Pläne haben, es zu entfernen, empfehlen wir, dass neuer Code modernere Alternativen verwendet.

Wir empfehlen dringend, dass Sie auch eine benutzerdefinierte Nachricht hinzufügen, z. B. eine neue API, die die alte ersetzt. Diese Nachricht wird an die Standardnachricht angehängt

.. legacy::

   New code should use :mod:`scipy.fft`.

erzeugt die folgende Ausgabe

Veraltet

Dieses Untermodul gilt als Legacy und wird keine weiteren Updates erhalten. Obwohl wir derzeit keine Pläne haben, es zu entfernen, empfehlen wir, dass neuer Code modernere Alternativen verwendet. Neuer Code sollte stattdessen scipy.fft verwenden.

Schließlich, wenn Sie eine Funktion, Methode (oder ein beliebiges benutzerdefiniertes Objekt) anstelle eines *Untermoduls* erwähnen möchten, können Sie ein optionales Argument verwenden

.. legacy:: function

Dies erzeugt die folgende Ausgabe

Veraltet

Diese Funktion gilt als Legacy und wird keine weiteren Updates erhalten. Obwohl wir derzeit keine Pläne haben, sie zu entfernen, empfehlen wir, dass neuer Code modernere Alternativen verwendet.

—