Rilascio di un pacchetto python - dovresti includere doc e test?

Question

Quindi, ho rilasciato una piccola libreria su Pypi, più come esercizio (per "vedere come è fatto") di qualsiasi altra cosa.

Ho caricato la documentazione su readthedocs e ho una suite di test nel mio repository git.

Dato che immagino che chiunque sia interessato a eseguire il test probabilmente clonerà semplicemente il repository e il documento è già disponibile online, ho deciso di non includere le cartelle doc e test nel pacchetto rilasciato, ed ero solo chiedendosi se quella fosse la cosa "giusta" da fare.

So che le risposte a questa domanda saranno piuttosto soggettive, ma ho ritenuto che fosse un buon posto per chiedere un senso di ciò che la comunità considera la migliore pratica.

Answer 1

Non è necessario, ma è consigliato includere documentazione e test di unità nella confezione.

Per quanto riguarda la documentazione:

Vecchio stile o per meglio dire rilasci di origine della vecchia scuola del software open source contengono la documentazione, si tratta di uno standard (dare un'occhiata al software GNU, per (de facto?) esempio). La documentazione fa parte del codice e dovrebbe far parte della versione, semplicemente perché una volta scaricato il rilascio sorgente sei indipendente. Sei mai stato nella situazione in cui sei stato su un treno da qualche parte, dove dovevi dare una rapida occhiata alla documentazione del modulo X ma non disponevi di accesso a Internet? E poi hai realizzato con sollievo che i documenti sono già lì, a livello locale.

Un altro punto importante a questo proposito è che la documentazione che si associa al codice si applica sicuramente alla versione del codice. Codice e documenti sono sincronizzati.

Un'altra cosa in particolare per quanto riguarda Python: è possibile scrivere i documenti utilizzando Sphinx e quindi creare un bellissimo output HTML basato sull'origine della documentazione nel processo di installazione del pacchetto. Ho visto vari pacchetti Python fare esattamente questo.

test relativi a:

Immaginate i test sono in bundle nella versione sorgente e sono facili da eseguire da parte dell'utente (si dovrebbe documentare come fare). Quindi, se l'utente osserva un problema con il tuo codice che non è così facile da rintracciare, può semplicemente eseguire i test di unità nel suo ambiente e vedere se almeno quelli stanno passando. In caso contrario, probabilmente hai assunto un presupposto errato specificando il comportamento del tuo codice, che è utile conoscere. Quello che voglio dire è: può essere molto buono per te come sviluppatore se rendi molto semplice all'utente l'esecuzione di test unitari.