python / python/devguide

Add discussion of doctesting interactive code examples.

Aperta
#1,134 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

topic-documentation topic-test type-feature
Lingua principale
Python
Stelle
2.1k
Fork
1k
Merge medio
2g 12h
PR unite (30g)
12

Descrizione

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.

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Direzione di ricerca

Leggi Documentation/Style Guide/Code Examples e la documentazione di doctest, in particolare gli esempi interattivi e le indicazioni sulle direttive. Esamina il controllo Docs/Doctest CI e le discussioni citate per stabilire la policy attuale, quindi aggiungi un riepilogo conciso nella sezione esistente o in una nuova sezione immediatamente successiva. Il lavoro è completato quando la guida spiega il comportamento previsto di doctest e le direttive rilevanti per gli esempi interattivi.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
python
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.