Tworzenie dokumentacji projektu w Python’ie za pomocą Sphinx

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

Poziom trudności
2.5/5

Któż lubi opisywać przepięknie napisany kod w dokumentacji? Nie wiem, na pewno nie ja. Pisząc oprogramowanie z nożem na gardle, bo projekt biegnie tak szybko,  ignorujemy jego dokumentowanie z braku czasu. Dużo mniejszym ‚złem’ jest opisywanie (najlepiej od razu), do czego służy każda kluczowa metoda i klasa bezpośrednio w kodzie. Tak naprawdę to bardzo dobra praktyka, tylko często pracochłonna. Jednak w połączeniu z narzędziem sphinx może okazać się jeszcze bardziej przydatna. Dzięki niemu wygenerujesz dokumentację projektu napisanego w Python’ie.

Instalacja

Aby zainstalować sphinx’a wystarczy użyć komendy pip install

pip install sphinx

Tu kończy się najłatwiejsza część. Postaram się w tym artykule przedstawić najszybszą i najprostszą drogę do skonfigurowania narzędzia sphinx.

Przygotowanie Kodu

Poniżej załączam przykładowy kod, który zapisałem w pliku test_file.py. Można zauważyć, że prócz standardowych elementów klas i metod dodane są komentarze w potrójnym cudzysłowie. Są to tak zwane brief’y. Zapis odbywa się  w konwecji docstring’ów, co jest opisane w PEP257. Na ich podstawie będzie powstawała dokumentacja. Różnią się one od siebie zapisem parametrów – Ale nie martwcie się, opowiem o tym w następnej części. Na razie skopiujcie poniższy kod do pliku test_file.py i czekajcie na dalsze instrukcje 😉 

  1. """
  2. test_file.py
  3. ====================================
  4. Text about module
  5. """
  6. class TestSphinx:
  7. """
  8. Text about that class
  9. Arg:
  10. one (str): test one
  11. two (int): test two
  12. """
  13. def __init__(self, one, two):
  14. self.one = one
  15. self.two = two
  16. @staticmethod
  17. def return_x(x):
  18. """
  19. About method return_x
  20. :param x: about x
  21. :return: x
  22. """
  23. return x
  24. def return_str_one(self):
  25. """
  26. About method return_one
  27. :return: str value of self.one
  28. """
  29. return str(self.one)

Konfiguracja

Tu zaczyna się cała zabawa. Spotkałem się z wieloma instrukcjami do tego narzędzia i doszedłem do wniosku, że gdyby ktoś chciałby z nich skorzystać dla samego wypróbowania sphinx’a, mogłoby to być uciążliwe. Więc w tym artykule wytyczam tutaj ścieżkę na skróty. Na początek przejdź w linii komend do folderu z projektem, w którym znajduje się przed chwilą utworzony plik. Teraz wygenerujemy dla niego dokumentację, za pomocą sphinx’a, skróconą metodą: 

sphinx-quickstart

Dostaniesz kolejno poniższe pytania. Nie zagłębiając się w ich potencjalne znaczenie, wypełnij je tak samo, jak ja:

Separate source and build directories (y/n) [n]: n
Project name: Test
Author name(s): Me
Project release []: 1

Pierwsze pytanie jest czysto estetycznym wyborem, jak mają wyglądać foldery po zakończonej powyższej operacji. Kolejne pytania dotyczą informacji, jakie będą wyświetlane na stronie z wygenerowaną dokumentacją. Ale spokojnie, ich zmiana będzie możliwa w pliku conf.py, który właśnie powstaje w folderze twojego projektu. Potrzebujemy go wyedytować, aby po automatycznej generacji poprawnie stworzyła się dokumentacja. Znajdź w pliku conf.py zmienną extensions, a następnie zmień jej wartość:

  1. extensions = ['sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.autodoc']

Pozwoli to na poprawne zadziałanie komendy sphinx-apidoc. W tym artykule ograniczę się do tak lakonicznej konfiguracji, ale tak jak mówiłem, jest to droga na skróty.

Generacja

Czas więc wygenerować dokumentację? Jeszcze nie. Na razie wygeneruję dodatkową konfigurację – żeby nie robić tego ręcznie. Służy do tego komenda sphinx-apidoc -f -o {konfiguracja} {projekt}. Wytłumaczmy kolejno dodatkowe zmienne: 
{konfiguracja} do podania docelowego folderu gdzie mają znaleźć za chwilę wygenerowane dodatkowe pliki konfiguracyjne
{projekt} ścieżka do projektu, z którego mają zostać wygenerowane – kropka oznacza, że są właśnie w tym folderze, w którym się znajdujemy.

sphinx-apidoc -f -o source/ .

Dalej przebywając w folderze z projektem, użyj komendy make html, by wygenerować dokumentację jako strona internetowa:

make html

Aby zobaczyć dokumentację, przejdź do folderu _build/html i otwórz plik index.html. Niech nie przeraża cię wygląd i brak informacji na stronie głównej – tym zajmiemy się w kolejne części serii. Aby zobaczyć efekty przygotowania i generacji wybierz na stronie link Index:

Tworzenie dokumentacji projektu w Pythonie za pomocą Sphinx image

Tak przygotowany możesz wypróbować sphinx’a we włanym projekcie. W kolejnej części zajmiemy się ‚uładnianiem’ dokumentacji i poszczególnymi jego składowymi. Bardziej szczegółowo przybliżę również konfigurację sphinx’a.

Dodaj komentarz