Jak udokumentować Kod Pythona za pomocą doxygen [zamknięty]

Lubię doxygen tworzyć dokumentację kodu C lub PHP. Mam nadchodzący projekt Pythona i myślę, że pamiętam, że Python nie ma Komentarzy /* .. */, a także ma swój własny obiekt samodokumentacji, który wydaje się być pythonicznym sposobem dokumentowania.

Ponieważ jestem zaznajomiony z doxygen, Jak mogę go użyć do stworzenia dokumentacji Pythona? Czy jest coś szczególnego, o czym muszę wiedzieć?

Author: Mogsdad, 2008-09-12
Source

5 answers

To jest udokumentowane na stronie internetowej doxygen, ale podsumowując tutaj:

Możesz użyć doxygen do udokumentowania kodu Pythona. Możesz użyć składni ciągów 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ć żadnej ze specjalnych poleceń doxygen .

Lub możesz (podobnie jak w językach C pod doxygen) podwoić znacznik komentarza (#) w pierwszej linii przed "członek": {]} 

## @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 określonego trybu wyjściowego Pythona, ale widocznie możesz poprawić wyniki, ustawiając OPTMIZE_OUTPUT_JAVA na YES.

Szczerze mówiąc, jestem trochę zaskoczony różnicą - wydaje się, że gdy doxygen wykryje komentarze w blokach ## lub blokach""", większość pracy zostanie wykonana i będziesz mógł używać specjalnych poleceń w obu przypadkach. Może oczekują, że ludzie używający """ będą stosować się do bardziej Pythonicznych praktyki dokumentacji i to by przeszkadzało specjalnym poleceniom doxygen?

 42
Author: Blair Conrad,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2008-09-12 11:11:03

Filtr wejściowy doxypy pozwala na użycie prawie wszystkich znaczników formatowania Doxygen w standardowym formacie docstring Pythona. Używam go do dokumentowania dużej mieszanej aplikacji C++ i Pythona i działa dobrze.

 64
Author: Michael Potter,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2015-06-28 00:28:20

Sphinx jest głównie narzędziem do formatowania dokumentów napisanych niezależnie od kodu źródłowego, jak to Rozumiem.

Do generowania dokumentów API z Pythona docstrings wiodącymi narzędziami są pdoc i pydoctor . Oto wygenerowane przez pydoctor dokumenty API dla Twisted I Bazaar .

Oczywiście, jeśli chcesz po prostu spojrzeć na docstrings podczas pracy nad rzeczami, jest to narzędzie wiersza poleceń" pydoc", a także narzędzie help() funkcja dostępna w interaktywnym interpreterze.

 20
Author: Allen,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2015-04-04 17:34:57

W końcu masz tylko dwie opcje:

Generujesz treść za pomocą Doxygen, lub generujesz treść 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 pokrewnymi projektami napisanymi w C lub C++, może to mieć sens. W tym celu możesz poprawić integrację między Doxygen i Pythonem za pomocą doxypypy.

  2. Sphinx : narzędzie defacto dla dokumentowanie projektu Pythona. Masz tu trzy opcje: ręczny, półautomatyczny (generowanie stubów) i w pełni automatyczny (Doxygen like).

    1. do dokumentacji manualnego API masz Sphinx autodoc. Świetnie jest napisać podręcznik użytkownika z osadzonymi elementami generowanymi przez API.
    2. dla półautomatycznych masz Sphinx autosummary. Możesz skonfigurować swój system budowania tak, aby wywoływał sphinx-autogen lub skonfigurować Sphinx za pomocą konfiguracji autosummary_generate. Będziesz musiał skonfigurować strony z autosumariami, a następnie ręcznie edytować strony. Masz opcje, Ale moje doświadczenie z tym podejściem polega na tym, ż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 dla generacji stubów, które będą wymagały ręcznej edycji i nic więcej. Jest jak skrót, który kończy się w instrukcji.
      3. W pełni automatyczny. To ma był wielokrotnie krytykowany i przez długi czas nie mieliśmy dobrego w pełni automatycznego generatora API Pythona zintegrowanego ze Sphinxem, dopóki nie pojawił się AutoAPI , który jest nowym dzieckiem w bloku. Jest to zdecydowanie najlepsze rozwiązanie do automatycznego generowania API w Pythonie (Uwaga: bezwstydna autopromocja).

Są inne opcje do zapamiętania:

  • Breathe : zaczęło się to jako bardzo dobry pomysł i ma sens, gdy pracujesz z kilkoma pokrewnymi projektami w innych języki używające Doxygen. Chodzi o to, aby użyć wyjścia XML Doxygen i dostarczyć go do Sphinx do wygenerowania API. Możesz więc zachować całą dobroć Doxygen i ujednolicić system dokumentacji w Sphinx. Super w teorii. Teraz, w praktyce, ostatni raz sprawdzałem projekt nie był gotowy do produkcji.
  • pydoctor *: bardzo szczególny. Generuje własne wyjście. Ma podstawową integrację ze Sphinx i kilka fajnych funkcji.
 13
Author: Havok,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2016-02-13 08:43:04

Innym bardzo dobrym narzędziem dokumentacji jest sphinx . Będzie on używany dla nadchodzącej dokumentacji Pythona 2.6 i jest używany przez django i wiele innych projektów Pythona.

Ze strony Sfinksa:

  • Format wyjściowy : HTML (w tym Windows HTML Help) i LaTeX, dla wersji PDF do wydruku
  • obszerne odsyłacze : znaczniki semantyczne i automatyczne linki do funkcji, klas, terminów słownikowych i podobnych elementy informacji
  • struktura hierarchiczna : ł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 podświetlanie za pomocą zakreślacza pigmentowego
  • rozszerzenia : automatyczne testowanie fragmentów kodu, włączanie docstringów z modułów Pythona i wiele innych
 12
Author: Peter Hoffmann,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/doraprojects.net/template/agent.layouts/content.php on line 54
2008-09-12 13:48:59