Ho un paio di moduli Python che devono essere eseguiti come script. Come dovrei scrivere le docstrings al modulo e il livello di funzione per rendere chiaro come eseguire e utilizzare il modulo?
Ho un paio di moduli Python che devono essere eseguiti come script. Come dovrei scrivere le docstrings al modulo e il livello di funzione per rendere chiaro come eseguire e utilizzare il modulo?
Personalmente uso le docstring per altri programmatori / installatori, lì documento lo scopo e tutti i dettagli di configurazione che è necessario esaminare raramente. Per la documentazione utente, utilizzo il modulo argparse in modo che gli utenti possano eseguire: program --help
import argparse
# other stuff
parser = argparse.ArgumentParser(
description='Path building utility.',
epilog="""Default operation is to read a list of directory
names from stdin and print a semi-colon delimited
path list to stdout. To terminate --add, --append,
--prepend or --remove list, use -- as in: {}
--remove *foo* *bar* -- input.file
""".format(os.path.basename(sys.argv[0])))
parser.add_argument('--add', '--prepend',
help='add specified directories to the front of the path',
dest='front', type=str, nargs='+', metavar='DIR', action='append')
# etc.
Mi piacerebbe imitare una pagina man(1)
NAME
this command does things
SYNOPSIS
command do-things nice
DESCRIPTION
things are nice when this command does them
Oltre a suggerimento di ZJR di imitare un uomo pagina , puoi anche fornire una dichiarazione d'uso, codici di ritorno e documentazione in codice.
Vorrei prendere in considerazione di fornire una dichiarazione di utilizzo che spiega come richiamare l'applicazione in modo chiaro e conciso. Ciò fornirebbe semplicemente un elenco degli argomenti, ciò che rappresentano gli argomenti, se un dato argomento è facoltativo e qualsiasi altra informazione pertinente. Questo sarebbe conveniente per gli utenti che invocano i tuoi script dalla riga di comando.
Per le applicazioni automatiche che chiamano i tuoi script, prenderei in considerazione l'utilizzo di vari codici di ritorno per documentare errori o altre considerazioni di esecuzione non standard. Questi possono essere facilmente analizzati e spostano la gestione di casi eccezionali (in particolare quelli che non puoi semplicemente gestire nello script) e la registrazione dell'evento nell'applicazione chiamante.
L'uso delle docstring potrebbe essere eccessivo, a seconda della complessità dello script, ma per gli sviluppatori futuri è necessaria una qualche forma di documentazione in codice (incluso te stesso in futuro). Includerei una panoramica di alto livello su ciò che lo script fa come la primissima cosa nel file. Anche il codice di autocertificazione sarebbe sempre d'aiuto, quindi assicurati di avere nomi di variabili validi. Se c'è una logica complessa, assicurati che sia chiaro cosa sta succedendo e perché hai preso le decisioni di progettazione che hai fatto con i commenti.
Leggi altre domande sui tag python documentation