Jak dokumentować kod Pythona: Epydoc, doxygen, Sphinx, ...?

Question

Nie jestem pewien, czy powinienem użyć Epydoc lub doxygen do dokumentowania mojego kodu Pythona. Obecnie wolałbym Epydoc, ponieważ jest wyspecjalizowany w Pythonie, a jego składnia nie różni się zbytnio od składni doxygen (do tej pory używałem do dokumentowania mojego kodu C/C++).

Wszelkie argumenty przeciwko Epydoc lub za używanie doxygen?

• http://epydoc.sourceforge.net/
• http://www.doxygen.org/
• http://sphinx.pocoo.org/

Answer 1

Epydoc było klasyczne narzędzie do generowania dokumentów. Jednak ostatnio wszyscy przenoszą się do sfinksa.

Powinieneś użyć epydoc lub możesz spróbować użyć sfinksa. Dokumentacja Pythona jest sama wykonana za pomocą sfinksa. Sphinx zapewnia lepszą kontrolę i lepszą dokumentację.

• http://sphinx-doc.org/

Nie ma nic złego w doxygen ale zapewnia wiele korzyści dla C/C++ programów. Ponieważ istnieją specjalistyczne narzędzia do pisania dla kodu Pythona, mogą zapewnić lepszą kontrolę nad generowaniem dokumentów.

Answer 2

Próbowałem Sphinx, epydoc i doxygen dla mojego projektu Pythona.

Sfinks nie działa dla mnie, ponieważ zależy to od możliwości importowania każdego modułu. Chociaż mój projekt działa dobrze i Sphinx mógł znaleźć swoje moduły, Sphinx nie był w stanie zaimportować większości modułów. Sfinks może być przydatny do ogólnej dokumentacji i do tworzenia podręcznika użytkownika, ale przynajmniej do udokumentowania mojego kodu źródłowego jest bezużyteczny. Wydaje się, że moduł Sphinx musi być w stanie działać samodzielnie. Ale w moim projekcie pierwszy moduł próbuje połączyć się z bazą danych. Jeśli połączenie z bazą danych się nie powiedzie, przestaje działać. Wiele innych modułów oczekuje kursora bazy danych. Jeśli połączenie z bazą danych nie zostało ustanowione, nie można ich zaimportować, a zatem Sphinx się nie powiedzie.

Doxygen działał dobrze. W połączeniu z doxypy jest jeszcze lepiej. Ma jednak pewne wady. Jeśli chcesz mieć listę numerowaną w kodzie źródłowym, nie dostaniesz jej w dokumentacji i wersecie. Co więcej, jeśli czytasz dokumentację, źródło nie jest widoczne.

Próbowałem więc Epydoc. Chociaż Epydoc nie był aktualizowany przez więcej niż 3 lata, a tym samym był zszyty, dla mnie okazało się zdecydowanie najlepszym narzędziem do dokumentowania kodu Pythona. Epydoc, taki sam jak Sphinx, próbuje zaimportować każdy moduł, ale jeśli import się nie powiedzie, wyświetla komunikat o błędzie, a następnie próbuje przeanalizować moduł, tak jak robi to doxygen. Dokumentacja wygenerowana przez Epydoc jest przyjemna i ma pewne zalety w porównaniu z doxygen: 1. Źródło, które jest udokumentowane, może być widoczne za pomocą jednego kliknięcia. 2. Listy numerowane w docstringu są również ponumerowane w dokumentacji.

Instalacja Sphinx jest dość skomplikowana, jeśli nie można użyć easy_install z połączeniem internetowym. To dlatego, że Sfinks zależy od innych pakietów. Doxygen można zainstalować tak łatwo, jak większość programów z instalatorem jednym kliknięciem. Ale DoxyPy i może być gaphviz powinien również zostać zainstalowany. Expydoc też można zainstalować za pomocą jednego kliknięcia, ale w systemie Windows 7 należy to zrobić jawnie jako admin, podczas gdy instalator Epydoc nie sprawdza sam, czy jest uruchamiany z wystarczającymi uprawnieniami. Zdobycie pierwszej użytecznej dokumentacji mojego projektu było zdecydowanie najłatwiejsze i najszybsze w Epydoc. Wreszcie Epydoc nadal może być rekomendowany jako najlepsze narzędzie do dokumentowania projektów Pythona. Sfinks może być dobrym narzędziem do tworzenia dokumentacji użytkownika.