Consolidate guidance on prompts in interactive code examples
Dieses Issue hat noch niemand übernommen.
- 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
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
Ö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