Lubię Doxygen do tworzenia dokumentacji kodu C lub PHP. Mam nadchodzący projekt w Pythonie i myślę, że pamiętam, że Python nie ma /* .. */komentarzy, a także ma własne narzędzie do samodzielnej dokumentacji, które wydaje się być pythonowym sposobem dokumentowania.
Skoro znam Doxygen, jak mogę go używać do tworzenia dokumentacji Pythona? Czy jest coś szczególnego, o czym muszę wiedzieć?
Odpowiedzi:
Jest to udokumentowane na stronie doxygen , ale podsumowując tutaj:
Możesz użyć doxygen, aby udokumentować swój kod w Pythonie. Możesz użyć składni ciągu dokumentacji Pythona:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
W takim przypadku komentarze zostaną wyodrębnione przez doxygen, ale nie będziesz mógł użyć żadnego ze specjalnych poleceń doxygen .
Lub możesz (podobnie jak w przypadku języków w stylu C pod doxygen) podwoić znacznik komentarza ( #) w pierwszej linii przed członkiem:
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
W takim przypadku możesz użyć specjalnych poleceń doxygen. Nie ma żadnego szczególnego trybu wyświetlania Python, ale można widocznie poprawić wyniki poprzez ustawienie OPTMIZE_OUTPUT_JAVAsię YES.
Szczerze mówiąc, jestem trochę zaskoczony różnicą - wygląda na to, że gdy doxygen może wykryć komentarze w blokach ## lub blokach "" ", większość pracy zostanie wykonana i będziesz mógł używać specjalnych poleceń w w obu przypadkach. Może spodziewają się, że ludzie używający "" "będą stosować się do większej liczby praktyk dokumentacji Pythona, a to będzie kolidować ze specjalnymi poleceniami doxygen?
Doxypy filtr wejściowy pozwala używać prawie wszystkich znaczników formatowania Doxygen w standardowym formacie docstring Pythona. Używam go do dokumentowania dużej mieszanej struktury aplikacji do gier w C ++ i Pythonie i działa dobrze.
Ostatecznie masz tylko dwie opcje:
Swoje treści generujesz za pomocą Doxygen, lub za pomocą Sphinx *.
Doxygen : nie jest to narzędzie z wyboru dla większości projektów Pythona. Ale jeśli masz do czynienia z innymi powiązanymi projektami napisanymi w C lub C ++, może to mieć sens. W tym celu możesz poprawić integrację między Doxygen i Python za pomocą doxypypy .
Sphinx : narzędzie defacto do dokumentowania projektu w języku Python. Masz tutaj trzy opcje: ręczną, półautomatyczną (generowanie odgałęzień) i w pełni automatyczną (jak Doxygen).
autosummary_generatepliku config. Będziesz musiał skonfigurować stronę z automatycznymi podsumowaniami, a następnie ręcznie edytować strony. Masz opcje, ale moje doświadczenie z tym podejściem jest takie, że wymaga zbyt dużej konfiguracji, a na końcu nawet po utworzeniu nowych szablonów znalazłem błędy i niemożność określenia dokładnie, co zostało ujawnione jako publiczne API, a co nie. Moim zdaniem to narzędzie jest dobre do generowania kodu źródłowego, które będzie wymagało ręcznej edycji i nic więcej. Jest jak skrót do instrukcji.Istnieją inne opcje, o których należy pamiętać:
__all__zmiennej explicite.
Sphinx to przede wszystkim narzędzie do formatowania dokumentów napisanych niezależnie od kodu źródłowego, jak rozumiem.
Do generowania dokumentów API z dokumentów Python wiodącymi narzędziami są pdoc i pydoctor . Oto dokumenty API wygenerowane przez pydoctora dla Twisted i Bazaar .
Oczywiście, jeśli chcesz po prostu rzucić okiem na ciągi dokumentacyjne podczas pracy nad różnymi rzeczami, dostępne jest narzędzie wiersza poleceń „ pydoc ”, a także help()funkcja dostępna w interaktywnym interpretatorze.
Innym bardzo dobrym narzędziem dokumentacyjnym jest sfinks . Będzie używany w przyszłej dokumentacji Pythona 2.6 i jest używany przez django i wiele innych projektów w Pythonie.
Ze strony sfinksa: