Sembra che ci sia una pletora di strumenti di documentazione per Python. Un altro che ho incontrato è epydoc. Sembra che Sphinx sia lo standard di fatto, perché è usato per generare i documenti ufficiali di Python. Qualcuno può per favore ordinare lo stato attuale degli strumenti di documentazione di Python per me?Qual è la relazione tra docutils e Sphinx?
epydoc e Sphinx sono diversi tipi di strumenti.
Sono gli stessi, nel senso che:
Essi sono diversi per la loro attenzione.
Quindi dipende da quanto lavoro si vuole mettere e cosa si sta documentando.
Grazie per aver spiegato cosa hanno in comune questi strumenti (ad es. La loro relazione con docutili) e le loro differenze. Che cosa rende epydoc migliore per la documentazione API e la Sfinge migliore per la documentazione funzionale? Hai detto che entrambi usano il reST. Sembra che ci sia un sacco di sovrapposizioni. È solo una questione di convenienza? Inoltre, lo sviluppo di epydoc non sembra essere molto attivo. L'ultimo impegno è stato a febbraio 2009, e l'ultima corrispondenza sulla lista di sviluppo è stata nel maggio 2009. – allyourcode
Bene, la risposta facile al perché uno è meglio in una cosa che un altro è che è il modo in cui sono stati progettati. Epydoc è fatto per estrarre il codice e Sphinx è fatto per generare molta documentazione dai file ReST che scrivi. C'è molta sovrapposizione. Sfinge è il nuovo ragazzo sul blocco. Ho sentito dire che in .7 avrà una generazione di auto-generazione molto migliore. Ho molto rispetto per Epydoc ma Sphinx sembra avere tutto lo slancio in questo momento. Mi piace perché sembra la documentazione di python.org E penso che sia migliore. –
Sphinx non è incentrato sulla documentazione generale dell'utente. Sfinge è uno strumento che ti aiuta a scrivere una documentazione completa e dettagliata, che semplicemente non puoi fornire concatenando le docstring. Sphinx supporterà anche i cosiddetti domini con 1.0 che permetteranno di documentare un progetto scritto in più lingue, ad esempio una webapp scritta in Python, Javascript e C. – DasIch
Sembra che Epydoc sia, se non morto, almeno struggente per i fiordi.
Sphynx con il comando sphinx-apidoc e l'estensione autodoc sembra essere l'opzione più popolare per i documenti API in questo momento.
Buoni esempi sono:
See: Should we use Epydoc, Sphinx or something else for documenting Python APIs? (SO5579198)
Sfinge incoraggia uno stile più narrativo che strumenti nello stampo javadoc , ma forse questa è una buona cosa?
Recentemente ho cambiato da Python2 a Python3 e ho trovato che non c'era alcun pacchetto Epydoc per Python3. Quindi sembra che con Python3 ci si concentri chiaramente sull'utilizzo di Sphinx come documentazione API.
Stato attuale? Cosa significa? Puoi ampliarlo? La Sfinge richiede docutili; epydoc può usare la stessa notazione RST. Cosa vuoi sapere? Può essere più preciso? –
ad es. Quali strumenti hanno un forte supporto per la comunità, uno sviluppo attivo? Esiste una soluzione incumbent, o ce ne sono molte con nessuna che abbia un seguito significativamente più ampio? – allyourcode
Forse dovresti modificare il titolo di questa domanda. –