Wydaje się, że istnieje mnóstwo narzędzi do dokumentacji dla Pythona. Kolejny, na który natknąłem, to epydoc. Wygląda na to, że Sphinx jest standardem de facto, ponieważ służy do generowania oficjalnych dokumentów w języku Python. Czy ktoś może posortować dla mnie aktualny stan narzędzi do dokumentacji Pythona?Jaki jest związek między docutils i Sphinx?
epydoc i Sphinx to różne rodzaje narzędzi.
one są takie same w tym, że:
Różnią się one w ich naciskiem.
To zależy od tego, ile pracy chcesz włożyć i co dokumentujesz.
Dzięki za wyjaśnienie, co te narzędzia mają wspólnego (np. Ich związek z docutils), a także ich różnice. Co sprawia, że epydoc jest lepszy do dokumentacji API i Sphinx lepiej do dokumentacji funkcjonalnej? Wspomniałeś, że obie używają reST. Wydaje się, że jest dużo nakładek. Czy to tylko kwestia wygody? Również rozwój epidoka nie wydaje się być bardzo aktywny. Ostatnie zatwierdzenie miało miejsce w lutym 2009 r., A ostatnia korespondencja na liście rozwijanej miała miejsce w maju 2009 r. – allyourcode
Cóż, łatwa odpowiedź na pytanie, dlaczego jedna jest lepsza z jednej, a druga to taka, w jakiej zostały zaprojektowane. Epydoc jest po prostu wyciągnąć z kodu i Sphinx jest stworzony, aby wygenerować wiele jego dokumentacji z plików ReST piszesz. Istnieje wiele pokryć. Sphinx jest nowym dzieckiem na bloku. Słyszałem plotki, że w .7 będzie miało o wiele lepsze auto-generacje. Mam dużo szacunku dla Epydoc, ale Sphinx wydaje się mieć teraz cały impet. Podoba mi się, ponieważ wygląda jak dokumentacja python.org I myślę, że wygląda lepiej. –
Sphinx nie koncentruje się na ogólnej dokumentacji użytkownika. Sphinx to narzędzie, które pomaga napisać pełną i szczegółową dokumentację, której po prostu nie można uzyskać, łącząc polecenia. Również Sphinx będzie obsługiwał tak zwane domeny z 1.0, które pozwolą ci dokumentować projekt napisany w wielu językach, na przykład webapp napisany w Pythonie, Javascript i C. – DasIch
Wygląda na to, że Epydoc jest, jeśli nie martwy, to przynajmniej podziwiany za fiordami.
Sfinks z poleceniem sphinx-apidoc i rozszerzeniem autodoc jest obecnie najbardziej popularną opcją dla dokumentów API.
Dobrymi przykładami są:
Patrz: Should we use Epydoc, Sphinx or something else for documenting Python APIs? (SO5579198)
Sphinx zachęca bardziej styl narracji niż narzędzia w formie javadoc , ale może to dobrze?
Niedawno zmieniłem z Python2 na Python3 i odkryłem, że nie było żadnego pakietu Epydoc dla Python3. Wygląda więc na to, że w Pythonie 3 wyraźnie skupiono się na używaniu Sphinx jako dokumentacji API.
Obecny stan? Co to znaczy? Czy możesz rozwinąć to? Sfinks wymaga docutils; epydoc może używać tej samej notacji RST. Co chcesz wiedzieć? Czy mógłbyś to sprecyzować? –
np. Jakie narzędzia mają silne wsparcie społeczności, aktywny rozwój? Czy istnieje rozwiązanie zasiedziałe, czy też wiele z nich nie ma znacznie większych po? – allyourcode
Może powinieneś edytować tytuł tego pytania. –