python / python/devguide

Add discussion of doctesting interactive code examples.

Offen
#1,134 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

topic-documentation topic-test type-feature
Vorherrschende Sprache
Python
Sterne
2.1k
Forks
1k
Ø Merge
2 T. 12 Std.
Gemergte PRs (30 T.)
12

Beschreibung

There have been various discussions about doctesting interactive code examples in the python docs. The consensus has been that it is desirable that they pass. Indeed, CI currently has a (pass-not-required) Tests / Docs / Doctest. (But it seems to be setup to be excessively lenient, passing many errors that are normally caught. Intended? Bug?) There has been additional discussion about use of particular features, such as doctest directives. An example from the doc:

The [ELLIPSIS](https://docs.python.org/3/library/doctest.html#doctest.ELLIPSIS) directive
gives a nice approach for the last example:
>>> C()  # doctest: +ELLIPSIS
<C object at 0x...>

Other people may remember such discussions better. In any case, a summary of current policy should be added either in
Documentation / Style Guide /Code Examples or in a new "Interactive Code Examples and Doctest" section immediately after.

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Lies Documentation/Style Guide/Code Examples und die doctest-Dokumentation, insbesondere die interaktiven Beispiele und die Hinweise zu Direktiven. Prüfe den Docs/Doctest CI-Check und die referenzierten Diskussionen, um die aktuelle Richtlinie zu ermitteln, und füge anschließend eine prägnante Zusammenfassung im bestehenden Abschnitt oder in einem neuen Abschnitt unmittelbar danach hinzu. Als erledigt gilt die Aufgabe, wenn der Leitfaden das erwartete doctest-Verhalten und relevante Direktiven für interaktive Beispiele erklärt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.