python / python/devguide

Consolidate guidance on prompts in interactive code examples

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

Dieses Issue hat noch niemand übernommen.

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

Beschreibung

In the Documentation chapter, Style Guide / Code Examples has

The ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly, where it is necessary to clearly differentiate between input lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations.

(Perhaps it should be mentioned here that doctesting the code example requires such differentiation and hence requires secondary prompts. Perhaps the primary prompt should also be left off.)

reStructured Text Markup / Additional Markup Constructs / Showing Code Examples has

Representing an interactive session requires including the prompts and output along with the Python code. No special markup is required for interactive sessions. After the last line of input or output presented, there should not be an “unused” primary prompt; this is an example of what not to do:

>>>1 + 1
2
>>>

I think both advices should be in the same place and a reference added in the other.

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

Öffne zuerst die verlinkten Abschnitte „Style Guide / Code Examples“ und „reStructured Text Markup / Showing Code Examples“. Führe ihre Hinweise zu interaktiven Eingabeaufforderungen an einer Stelle zusammen, füge an der anderen Stelle einen Verweis hinzu und stelle sicher, dass die daraus entstehenden Hinweise sekundäre Eingabeaufforderungen, doctesting und das ungenutzte Beispiel für die primäre Eingabeaufforderung abdecken.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Aktivitätsstatus
Veraltet
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
50/100

Neue Issues direkt in Ihr Postfach

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