w tym artykule omówimy (bardzo) podstawy generowania dokumentacji z docstrings w kodzie Pythona. Jest to trochę grind, ale po zrobieniu tego raz, łatwo będzie powtórzyć proces w każdym nowym projekcie.

dla naszych celów Zakładamy, że (1) wierzysz w wartość dokumentowania swojego kodu; (2) chcesz wygenerować dokumenty z Twoich docstrings i (3) zdecydowałeś się użyć Sfinksa do wykonania pracy.

wreszcie, zakłada się, że masz już skonfigurowane odrębne środowisko wirtualne dla swojej aplikacji. Dla zainteresowanych bardzo lubię menedżera środowiska pyenv. Ma nawet poręczny instalator.

musisz zainstalować sphinx poprzezpip. Co najmniej będziesz potrzebował wersji 1.3, ale o ile nie masz dobrego powodu, powinieneś zainstalować najnowszą wersję.

$ pip install sphinx

Krok 2: Skonfiguruj swój projekt za pomocą Quickstart

podczas instalacji pakietu sphinx ustawiono również wiele narzędzi wiersza poleceń.

jeden z nich, sphinx-quickstart szybko wygeneruje podstawowy plik konfiguracyjny i strukturę katalogów dla Twojej dokumentacji.

Uruchom to polecenie w katalogu bazowym projektu (tj. katalogu głównym repo Git). Zadaje ci wiele pytań, które zadecydują o jego działaniach. Zazwyczaj możesz zaakceptować wartości domyślne, ale oto kilka sugestii, kiedy należy odbiegać od wartości domyślnych:

Po uruchomieniu programu zauważysz, że w katalogu projektu istnieje nowy folder ./docs. Ponadto w tym folderze znajdują się trzy nowe pliki: conf.pyindex.rst IMakefile.

Krok 3: dostosowanie conf.py plik

domyślny plikconf.py wygenerowany przez narzędzie quickstart ma około 170 linii, więc nie będę tu umieszczać całości. Istnieje jednak kilka elementów, które musimy zaktualizować przed kontynuowaniem.

powiedz Sphinxowi, gdzie znajduje się twój pakiet Pythona

pierwszą rzeczą, którą musimy zrobić, to wskazać, gdzie znajduje się pakiet Pythona zawierający Twój kod programu w stosunku do plikuconf.py. Jeśli struktura katalogów wygląda tak:

musisz wskazać w plikuconf.py, że Sphinx musi przejść „w górę” o jeden poziom katalogu, aby znaleźć pakiet Pythona.

miejsce na umieszczenie tego jest na końcu pierwszej sekcji pliku konfiguracyjnego. Tuż przed ustawieniamiGeneral Configuration zobaczysz to:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

gdyby nie został skomentowany, oznaczałoby to, że Twój Pakiet znajduje się w tym samym katalogu co plikconf.py. Musisz zmienić to na:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Dodaj „Napoleon” do listy rozszerzeń Sphinxa, aby użyć

Po wyjęciu z pudełka, Sphinx rozumie tylko docstringi napisane w tradycyjnym reStructuredText. Jeśli miałeś, ahem, przywilej pracy z takimi dokumentami, będziesz wiedział, że są one bólem do pisania i wcale nie są przyjazne człowiekowi do czytania, patrząc na nie bezpośrednio w kodzie źródłowym.

Rozszerzenie Napoleon pozwala Sphinxowi zrozumieć docstringi napisane w dwóch innych popularnych formatach: NumPy i Google.

wszystko, co musimy zrobić, to dodaćsphinx.ext.napoleon do listyextensions. Po zakończeniu powinno to wyglądać tak:

extensions = 

Krok 4: zaktualizuj indeks.rst

w tym momencie możemy uruchomić proces budowania, aby wygenerować naszą dokumentację. Ale to byłoby rozczarowujące. Oto co dostalibyśmy:

chociaż chciałbym, aby Sfinks znalazł dla nas nasze docstringi i uporządkował je ładnie bez dalszej konfiguracji, nie jest to aż tak magiczne.

aby przejść dalej, będziemy musieli wprowadzić kilka drobnych modyfikacji do naszego plikuindex.rst, który obecnie wygląda tak:

zacznijmy od pozbycia się komentarza na górze, który jest po prostu szumem:

teraz, chociaż istnieje wiele rzeczy, które moglibyśmy tutaj zrobić, ograniczymy się do absolutnego minimum, aby utrzymać ten post w nieco rozsądnej długości.

Czy widzisz, że .. toctree:: linia? To właśnie Sfinks nazywa dyrektywą. Musimy dodać dyrektywy autodoc do naszego plikuindex.rst, aby Sphinx wiedział, na jakich obiektach kodu chcemy użyć rozszerzenia autodoc.

dodam jedną wskazującą na Sfinksa, że chcę, aby dokumentował publicznych członków mojegomain.py Moduł wewnątrzmy_project pakiet:

Krok 5: Napisz swoje Docstrings

nie będziemy opisywać jak pisać docstrings w stylu Numpy lub Google w tym poście.

jednak oto kod z main.py, który zawiera kilka prostych docstringów w stylu NumPy, które zostaną odebrane przez naszą dyrektywę autodoc:

Krok 6: Wygeneruj swoje dokumenty!

teraz nadszedł czas, aby czerpać korzyści z pracy. Upewnij się, że znajdujesz się w katalogu ./docs I wykonaj następujące czynności: make html

Jeśli do tej pory śledziłeś, powinieneś zobaczyć coś takiego:

dopóki widzisz ten wspaniały komunikat build succeeded na końcu, jesteś gotowy do Idź i zobacz swoje piękne stworzenie.

w wierszu poleceń wykonajopen _build/html/index.html (lub po prostu otwórz tę stronę w przeglądarce ręcznie) i powinieneś zobaczyć coś takiego:

kolejne kroki

właśnie porysowaliśmy powierzchnię i nadal jest wiele brodawek w naszej prostej dokumentacji.

w następnym poście na ten temat zagłębimy się w dyrektywy rozszerzenia autodoc i uzyskamy większą kontrolę nad treścią i wyglądem naszej dokumentacji.