Come dovrei documentare uno script Python?

6

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?

    
posta murgatroid99 24.08.2011 - 17:17
fonte

3 risposte

5

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.
    
risposta data 24.08.2011 - 18:07
fonte
4

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
    
risposta data 24.08.2011 - 17:25
fonte
1

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.

    
risposta data 24.08.2011 - 17:46
fonte

Leggi altre domande sui tag