sphinx - jak generować dokumentacje z projektu w Python'ie #2: Wygląd i edycja

Po tym, jak stworzyliśmy zarys naszej przyszłej dokumentacji, w pierwszej części serii o narzędziu sphinx. Czas zająć się wyglądem, i jego manualną edycją. Automatyczna generacja dokumentacji nie obejdzie się bez delikatnych manualnych modyfikacji.

Porządki

Zacznijmy więc od małych porządków w repozytorium, żeby pliki i foldery sphinx’a nie mieszały się z plikami wytwarzanego przez nas kodu. Utwórz folder (w moim przypadku nazwę go sphinx) i przenieś wszystkie pliki i foldery, które zostały wcześniej wygenerowane przez sphinx’a: _static, _templates, source, config.py, index.rst, make.bat, Makefile. Niestety, gdy wejdziesz do nowoutworzonego folder i wpiszesz po prostu make html, sphinx nie spostrzeże się sam, że coś się zmieniło. Wejdź do pliku config.py i odkomentuj poniższe linijki, po czym dodaj dodatkową kropkę do nawiasu (suma kropek równa jest 2 😉 ) i cudzysłowie (co będzie oznaczać wyjście do folderu poniżej). Pamiętaj, że teraz make html wykonujesz z poziomu nowo utworzonego folderu.

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

Gdy już upiększyliśmy przejrzystość naszych folderów czas zaingerować w sam wygląd.

Dokumentacja w stylu Google’a

Nie każdemu przypadnie do gustu surowość standardowego wyglądu. Możemy go zmienić w bardzo prosty sposób. Zacznijmy od zainstalowania sphinx_rtd_theme:

pip install sphinx_rtd_theme

Następnie dodamy nowy wygląd do dokumentacji, edytując plik config.py. Dodaj do niego import sphinx_rtf_theme i następnie zmień wartość zmiennej html_theme_path i html_theme jak poniżej:

import sphinx_rtd_theme
html_theme_path = ['sphinx_rtd_theme.get_html_theme_path()']
html_theme = 'sphinx_rtd_theme'

Teraz wystarczy wywołać komendę make html i podziwiać nowy wygląd:

Na powyższym screenie zauważyć możemy, że sphinx oprócz naturalnego podziały na klasy i metody wyciągnął z brief’a dodatkowe informacje. Prezentację parametrów (Parameters) i zwracanych wartości (Returns) uzyskaliśmy dzięki użyciu składni w poniższym kodzie.

def return_x(x):
    """
    About method return_x
 
 
    :param x: about x
    :return: x
    """
    return x

Wystarczy, że w brief’ie użyjemy :param {argument}:, aby odnieść się do argumentów naszej funkcji i :return: – aby dodać informacje o zwracanej wartości. Zwiększa to czytelność i przejrzystość dokumentacji.

Edycja plików rst

Może najpierw dwa słowa czym są pliki o rozszerzeniu rst. W telegraficznym skrócie są to szablony, z których wygenerujemy nasz kod strony głównej i wszystkich podstron. W poprzedniej części serii zostały one stworzone automatycznie w folderze source. Plik index.rst jest nieodłączną częścią sphinx’a, gdyż od niego zależy, co znajdzie się na stronie głównej. I właśnie teraz zajmiemy się edycją tego pliku. Na początek do pliku index.rst dodaj poniższe linijki.

„test_file.py module” stanie się jednym z podtytułów strony głównej,
automodule oznacza, z jakiego pliku mają być pobrane dane do wczytania brief’ów,
dodanie linijki members, pozwoli na wyświetlenie zawartości pliku.

test_file.py module
=================
.. automodule:: test_file
:members:

Jak we wszystkich wcześniejszych przypadkach użyj komendy make html i sprawdź, jak teraz wygląda strona główna twojej dokumentacji.

Teraz gdy już możemy podziwiać dużo ładniejszą wersję naszej dokumentacji. Czas na dokładniejsze zapoznanie się z tym, co możemy w niej wyświetlić. W kolejnej części tworzenia dokumentacji za pomocą sphinx’a przyjrzymy się bliżej sekcji docstringów i sposobami ich wyświetlania.