Migrazione da Javadoc a Python Documentazione

Question

Quindi mi sono un po 'abituato alla documentazione di stile Javadoc. Guardando attraverso vari esempi di codice Python, sto scoprendo che, a prima vista, la documentazione sembra che manchi di molte informazioni.

Il buono: raramente si vedono frammenti di documentazione evidenti. Le didascalie sono in genere un paragrafo o meno del markup inglese che si integra invece di distinguersi su righe separate.

Il male: in congiunzione con la digitazione anatra di Python, trovo che molte funzioni non sono chiare sui parametri che si aspettano. Non c'è alcun tipo di suggerimento (suggerimento di anatre?) E spesso sarebbe bello avere qualche idea che il parametro dovrebbe essere simile a una lista, a una stringa, simile a un flusso.

Ovviamente, Javadoc è stato progettato per un linguaggio di livello inferiore, senza grandi capacità di introspezione di Python, che potrebbe spiegare la filosofia della documentazione meno dettagliata.

Qualche consiglio sugli standard di documentazione Python e sulle best practice?

Answer 1

Il formato reStructuredText è stato progettato in risposta alla necessità di una documentazione Python che potrebbe essere incorporato in docstring, quindi la cosa migliore è quello di imparare riposare e formattare i docstring con questo formato. Si potrebbe trovare, come ho fatto io, che poi va in formato quasi qualsiasi documentazione in resta, ma questo è un punto di lato :-)

Per specificamente documentare il codice Python, il sistema Sphinx è un insieme di estensioni al formato reST e un sistema di generazione per il rendering dei documenti. Poiché è stato progettato per documentare Python stesso, inclusa la libreria standard, Sphinx consente una documentazione molto ben strutturata del codice sorgente, incluse ovviamente le specifiche delle firme delle funzioni come richiesto. Permette di costruire una suite di documentazione completa, sia autoestraente che scritta a mano, utilizzando lo stesso sistema di formattazione.

Se solo vuole documentazione generata dal codice sorgente, poi Epydoc sarà estrarre documentazione API dal codice sorgente di; anche questo legge la formattazione della ripetizione per il testo.