sphinx — jak generować dokumentacje z projektu w Python’ie #2​

sphinx — jak generować dokumentacje z projektu w Python'ie #2

Poziom trudności
2.5/5

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.

  1. import os
  2. import sys
  3. 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: 

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

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

sphinx — jak generować dokumentacje z projektu w Pythonie #2​ image

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.

  1. def return_x(x):
  2. """
  3. About method return_x
  4. :param x: about x
  5. :return: x
  6. """
  7. 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
=================
.. 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.

Dodaj komentarz