sphinx - jak generować dokumentacje z projektu w Python'ie #1: Podstawy

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 😉

"""
test_file.py
====================================
Text about module
"""
 
class TestSphinx:
    """
    Text about that class
 
    Arg:
    one (str): test one
    two (int): test two
    """
    def __init__(self, one, two):
        self.one = one
        self.two = two
 
    @staticmethod
    def return_x(x):
        """
        About method return_x
 
        :param x: about x
        :return: x
        """
        return x
 
    def return_str_one(self):
        """
        About method return_one
        :return: str value of self.one
        """
        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ść:

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.

{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:

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.