Last modified: July 05, 2024

This article is written in: 🇵🇱

Dokumentacja

Dokumentacja stanowi kluczowy komponent każdego projektu programistycznego, umożliwiając użytkownikom zrozumienie funkcjonalności, struktury oraz sposobu działania aplikacji. W Pythonie jednym z popularnych narzędzi służących do tworzenia profesjonalnej dokumentacji jest SPHINX. Pozwala on na generowanie dokumentacji w różnorodnych formatach, w tym HTML, LaTeX, epub czy plain text. Istnieje również możliwość konwersji dokumentacji z formatu LaTeX do PDF.

Rozpoczęcie z Sphinx

Aby zainicjować szkielet dokumentacji, potrzebujesz uruchomić następującą komendę:

sphinx-quickstart

Po uruchomieniu tej komendy, SPHINX poprosi cię o podanie kilku szczegółów dotyczących twojego projektu. Na podstawie udzielonych odpowiedzi, narzędzie to wygeneruje odpowiednie pliki startowe i przygotuje je do uzupełnienia konkretną treścią.

Aby skompilować i wygenerować dokumentację opartą o istniejące pliki konfiguracyjne, wykorzystaj:

make html

Po pomyślnym wykonaniu tej komendy, jeśli wszystko przebiegnie bez błędów, SPHINX poinformuje cię o sukcesie. W przypadku wystąpienia problemów, zostaniesz poinformowany za pomocą komunikatów błędów.

reStructuredText i jego zastosowanie w Sphinx

reStructuredText (rST) to elastyczny i rozbudowany język znaczników przeznaczony do tworzenia dokumentacji i prostych stron internetowych. W porównaniu z popularnym językiem markdown, rST oferuje znacznie bogatszy zestaw funkcji, co czyni go idealnym narzędziem do tworzenia rozbudowanej dokumentacji.

Kluczowe cechy reStructuredText

  1. reStructuredText oferuje zaawansowane formatowanie, takie jak przypisy dolne, tabele, linki oraz definicje, które nie są tak łatwo dostępne w markdown.

  2. Dzięki wsparciu dla różnych pluginów, reStructuredText można łatwo dostosować do konkretnych potrzeb projektu.

  3. reStructuredText jest głównym formatem używanym przez Sphinx, popularne narzędzie do generowania dokumentacji. Plik index.rst jest centralnym punktem dokumentacji w Sphinx, zawierającym główną strukturę oraz linki do innych części dokumentacji.

  4. Linkowanie do innych plików czy sekcji w reStructuredText jest bardziej intuicyjne i przejrzyste, co ułatwia utrzymanie spójności w rozbudowanych dokumentacjach.

  5. Sphinx, korzystając z plików reStructuredText, umożliwia generowanie dokumentacji w różnych formatach, w tym w HTML. Wystarczy użyć komendy make html, aby przekształcić pliki reStructuredText w elegancką stronę internetową.

Podstawowe formatowanie w reStructuredText

Nagłówki

Nagłówki są tworzone poprzez dodanie linii znaków pod tekstem.

Nagłówek 1
==========

Nagłówek 2
----------

Nagłówek 3
^^^^^^^^^^

Wyróżnienia tekstu

*Pochylenie*

**Pogrubienie**

`Poczwórny akcent dla kodu źródłowego

Listy

- Element 1
- Element 2
    - Pod-element 2.1
    - Pod-element 2.2
- Element 3

Linki

Link tekstowy <http: example.com="">`_

Obrazy

.. image:: ścieżka/do/obrazu.jpg
   :alt: Tekst alternatywny

Tabele

+---------------+-------------+-------------+
| Nagłówek 1    | Nagłówek 2  | Nagłówek 3  |
+---------------+-------------+-------------+
| komórka 1.1   | komórka 1.2 | komórka 1.3 |
| komórka 2.1   | komórka 2.2 | komórka 2.3 |
+---------------+-------------+-------------+

Przypisy

Przykład tekstu z przypisem.[1]

.. [1] Tekst przypisu dolnego.

Dyrektywy

Dyrektywy służą do wstawiania różnych elementów, takich jak obrazy, tabele czy fragmenty kodu.

.. note:: To jest notatka.

.. warning:: To jest ostrzeżenie.

.. code-block:: python

    def funkcja():
        print("Przykład kodu")

Automatyczne generowanie dokumentacji dla API

Współczesne aplikacje często korzystają z interfejsów API, które pozwalają na komunikację między różnymi usługami. Aby ułatwić korzystanie z takiego API, kluczowe jest dostarczenie dokładnej, ale i czytelnej dokumentacji. Automatyczne generowanie dokumentacji może znacząco przyspieszyć ten proces, jednocześnie zapewniając, że jest ona zawsze aktualna. Proces ten pozwala nam zaoszczędzić czas oraz minimalizuje ryzyko błędów i nieścisłości wynikających z ręcznego pisania dokumentacji.

W Pythonie możemy wykorzystać narzędzie Sphinx do generowania dokumentacji, a w kontekście API, jego rozszerzenie sphinx-apidoc jest szczególnie przydatne.

Krok po kroku

Początkowa struktura projektu może wyglądać następująco:

my_project/
├── my_module/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
└── setup.py

I. Instalacja sphinx-apidoc:

pip install sphinx

Sphinx to narzędzie, które pozwala na łatwe tworzenie dokumentacji w formacie reStructuredText (rst) lub Markdown, a następnie konwertowanie jej na różne formaty wyjściowe, takie jak HTML, PDF, czy ePub. Sphinx jest szeroko stosowany w społeczności Pythona i jest wspierany przez wiele narzędzi CI/CD.

pip install sphinx-apidoc

Ten pakiet rozszerza funkcjonalność Sphinxa, umożliwiając automatyczne skanowanie kodu źródłowego i generowanie odpowiednich plików dokumentacji. Dzięki sphinx-apidoc, każdy moduł i pakiet w projekcie zostanie opisany na podstawie docstringów, co pozwala na zachowanie spójności między kodem a dokumentacją.

II. Generowanie dokumentacji dla API

mkdir docs

sphinx-apidoc -o docs/source/api/ <ścieżka do katalogu z kodem>

W powyższym poleceniu <ścieżka do katalogu z kodem> zastąp ścieżką do katalogu zawierającego twój kod źródłowy. Polecenie to skanuje wskazany katalog i generuje pliki .rst dla wszystkich modułów i pakietów w projekcie. Dla naszego przykładu to będzie:

sphinx-apidoc -o docs/source/api/ ../my_module/

Po tym kroku struktura katalogów będzie wyglądać następująco:

my_project/
├── docs/
│   ├── Makefile
│   ├── build/
│   └── source/
│       ├── api/
│       │   ├── my_module.module1.rst
│       │   ├── my_module.module2.rst
│       │   └── my_module.rst
│       ├── conf.py
│       ├── index.rst
│       └── _static/
│       └── _templates/
├── my_module/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
└── setup.py

III. Konfiguracja Sphinx i dodanie wygenerowanej dokumentacji do głównej zawartości

Aby wygenerowane pliki .rst były widoczne w głównej dokumentacji, musisz je dodać do pliku index.rst, który jest głównym plikiem startowym dokumentacji Sphinx. Otwórz plik index.rst i dodaj do niego wpis dla wygenerowanej dokumentacji API:

.. toctree::
   :maxdepth: 2
   :caption: Spis treści:

   api/index

W powyższym przykładzie api/index odnosi się do głównego pliku indeksu wygenerowanego przez sphinx-apidoc. Upewnij się, że ścieżka jest zgodna z rzeczywistą lokalizacją pliku.

IV. Generowanie strony internetowej z dokumentacją:

Po dodaniu wygenerowanych plików do głównego indeksu, możemy przystąpić do generowania końcowego formatu dokumentacji. Najczęściej używanym formatem jest HTML, który umożliwia przeglądanie dokumentacji w przeglądarce internetowej. Aby wygenerować dokumentację w formacie HTML, wykonaj następujące polecenie w katalogu głównym dokumentacji:

make html

Po zakończeniu procesu, wygenerowane pliki HTML będą dostępne w katalogu _build/html. Możesz je otworzyć w przeglądarce internetowej, aby przejrzeć dokumentację.

Po tym kroku struktura katalogów będzie wyglądać następująco:

my_project/
├── docs/
│   ├── Makefile
│   ├── build/
│   │   └── html/
│   │       ├── index.html
│   │       ├── genindex.html
│   │       ├── ...
│   └── source/
│       ├── api/
│       │   ├── my_module.module1.rst
│       │   ├── my_module.module2.rst
│       │   └── my_module.rst
│       ├── conf.py
│       ├── index.rst
│       └── _static/
│       └── _templates/
├── my_module/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
└── setup.py

V. Automatyzacja aktualizacji dokumentacji

Automatyzacja procesu aktualizacji dokumentacji jest kluczowa, aby zawsze odzwierciedlała bieżący stan kodu. Można to osiągnąć na kilka sposobów:

# .pre-commit-config.yaml
repos:
- repo: local
  hooks:
  - id: generate-docs
    name: Generate Sphinx Documentation
    entry: sphinx-apidoc -o docs/source/api/ ../my_module/ && make -C docs html
    language: system
    stages: [commit]

VI. Dostosowanie wyglądu dokumentacji

Sphinx umożliwia szerokie możliwości dostosowywania wyglądu i funkcjonalności dokumentacji. Możesz zmienić motyw, dodawać własne style CSS, a także modyfikować szablony HTML. Wszystkie te ustawienia znajdują się w pliku conf.py, który jest głównym plikiem konfiguracyjnym Sphinx:

html_theme = 'alabaster'

html_static_path = ['_static']
html_css_files = [
    'custom.css',
]

Sphinx pozwala na pełną personalizację szablonów HTML. Możesz tworzyć własne szablony lub modyfikować istniejące, dodając pliki HTML do katalogu _templates.

VII. Konsystencja i dokładność

Automatyczne narzędzia generowania dokumentacji, takie jak sphinx-apidoc, zapewniają, że dokumentacja jest spójna i dokładna. Dzięki automatycznemu skanowaniu kodu, narzędzia te są w stanie wygenerować dokumentację, która odzwierciedla rzeczywisty stan kodu, minimalizując ryzyko błędów i niezgodności.

VIII. Oszczędzanie czasu

Ręczne pisanie i aktualizowanie dokumentacji może być bardzo czasochłonne. Automatyzacja tego procesu pozwala zaoszczędzić czas programistów, który mogą przeznaczyć na rozwijanie funkcjonalności aplikacji, zamiast martwić się o ręczne aktualizowanie dokumentacji.

IX. Lepsza współpraca zespołowa

Dzięki automatycznemu generowaniu dokumentacji, wszyscy członkowie zespołu mają dostęp do najnowszych informacji o API. To ułatwia współpracę, ponieważ wszyscy członkowie zespołu mogą korzystać z aktualnej dokumentacji, co minimalizuje ryzyko nieporozumień i błędów.

X. Łatwość użycia

Narzędzia takie jak Sphinx i sphinx-apidoc są stosunkowo łatwe do skonfigurowania i użycia. Nawet mniej doświadczeni programiści mogą szybko nauczyć się korzystać z tych narzędzi, co czyni je dostępnymi dla szerokiego grona użytkowników.

Linki

Spis Treści

  1. Dokumentacja
    1. Rozpoczęcie z Sphinx
  2. reStructuredText i jego zastosowanie w Sphinx
    1. Kluczowe cechy reStructuredText
    2. Podstawowe formatowanie w reStructuredText
      1. Nagłówki
      2. Wyróżnienia tekstu
      3. Listy
      4. Linki
      5. Obrazy
      6. Tabele
      7. Przypisy
      8. Dyrektywy
    3. Automatyczne generowanie dokumentacji dla API
      1. Krok po kroku
    4. Linki