Jak udokumentować kod Pythona za pomocą Doxygen [zamknięte]

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ć?

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 *.

1. 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 .

2. 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).

   1. Do ręcznej dokumentacji API masz Sphinx autodoc . Wspaniale jest napisać podręcznik użytkownika z osadzonymi elementami generowanymi przez API.
   2. Dla półautomatów masz autopodsumowanie Sphinx . Możesz albo skonfigurować swój system kompilacji, aby wywoływał sphinx-autogen, albo skonfigurować Sfinksa za pomocą 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.
   3. Całkowicie automatyczny. Było to wielokrotnie krytykowane i przez długi czas nie mieliśmy dobrego, w pełni automatycznego generatora API Pythona zintegrowanego ze Sphinxem, dopóki nie pojawiło się AutoAPI , które jest nowym dzieckiem w bloku. Jest to zdecydowanie najlepsze rozwiązanie do automatycznego generowania API w Pythonie (uwaga: bezwstydna autopromocja).

Istnieją inne opcje, o których należy pamiętać:

• Oddychaj : to był bardzo dobry pomysł i ma sens, gdy pracujesz z kilkoma powiązanymi projektami w innych językach, które używają Doxygen. Chodzi o to, aby użyć wyjścia Doxygen XML i przesłać go do Sphinx w celu wygenerowania API. Możesz więc zachować całą dobroć Doxygen i ujednolicić system dokumentacji w Sphinx. Niesamowite w teorii. Teraz w praktyce ostatnim razem, gdy sprawdzałem, projekt nie był gotowy do produkcji.
• pydoctor *: Bardzo szczególne. Generuje własne wyjście. Ma podstawową integrację ze Sphinxem i kilka fajnych funkcji.

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:

• Formaty wyjściowe : HTML (w tym Pomoc HTML systemu Windows) i LaTeX, dla wersji PDF do druku
• Obszerne odsyłacze : znaczniki semantyczne i automatyczne linki do funkcji, klas, terminów słownikowych i podobnych informacji
• Hierarchiczna struktura : łatwa definicja drzewa dokumentów z automatycznymi linkami do rodzeństwa, rodziców i dzieci
• Indeksy automatyczne : indeks ogólny oraz indeks modułu
• Obsługa kodu : automatyczne wyróżnianie za pomocą zakreślacza Pygments
• Rozszerzenia : automatyczne testowanie fragmentów kodu, dołączanie ciągów dokumentów z modułów Pythona i nie tylko