Sphinx (generator dokumentacji)

Sphinx
Autor	Georg Brandl
Pierwsze wydanie	21 marca 2008(dts)
Aktualna wersja stabilna	8.1.3; (13 października 2024) [±]
Język programowania	Python
Platforma sprzętowa	wieloplatformowy
Rodzaj	generator dokumentacji
Licencja	BSD
	Strona internetowa

Sphinx – system tworzenia i generowania dokumentacji technicznej, który konwertuje pliki źródłowe reStructuredText najczęściej do dokumentu HTML^[1], ale możliwe jest również określenie innych formatów wyjściowych, np.: LaTeX, PDF, ePUB, man^[2].

Zastosowanie zwykłego tekstu (ang. plain text) podczas tworzenia dokumentacji w systemie Sphinx umożliwia nie tylko łatwe dostosowanie formatu wyjściowego do oczekiwań odbiorców, ale staje się szczególnie przydatne w przypadku korzystania z systemu kontroli wersji, który umożliwia śledzenie zmian w plikach źródłowych pisanych w języku znaczników reStructuredText, w odróżnieniu od sytuacji, kiedy dokumentacja pisana jest w plikach binarnych, takich jak np. format .doc w (Microsoft Word). Dodatkowo zwykły tekst może być z łatwością przenoszony między różnymi platformami i systemami operacyjnymi, dzięki temu dokumentacja napisana w systemie Sphinx jest wysoce przenoszalna^[3].

Zarys historii

Pierwsza, publiczna wersja systemu o numerze 0.1.61611 została wydana 21 marca 2008 r.^[4] System został opracowany specjalnie na potrzeby tworzenia dokumentacji dla języka programowania Python^[5]. Wcześniej dokumentacja języka Python tworzona była w systemie składu tekstu LaTeX. W tamtym okresie, w latach 80. i na początku lat 90. XX wieku, większość dokumentacji była drukowana i nie była dostępna online. Zespół developerów Pythona zaprzestał korzystania z drukowanej dokumentacji, a zamiast tego zaproponował dostęp online do dokumentów HTML. Generowanie HTML z formatu LaTeX było skomplikowane, dlatego też – podczas rozwoju Pythona w wersji 2.6 – Georg Brandl stworzył system Sphinx^[6].

Zastosowanie

Od czasu wydania w 2008 r., Sphinx został zaadaptowany dla innych, ważnych projektów Pythona, takich jak m.in.: Bazaar, SQLAlchemy, MayaVi, Sage, SciPy, Django, Pylons^[7].

Poza tworzeniem dokumentacji, system Sphinx został wykorzystany do budowy stron internetowych^[8]. Może też być wykorzystywany do składu i przygotowywania książek do druku^[9].

W celu łatwiejszego zarządzania stworzoną dokumentacją, w kwietniu 2010 r. utworzony został projekt Read the Docs^[10]. Read the Docs (RTD) oferuje import dokumentacji, jej przeglądanie oraz darmowy hosting. RTD posiada funkcję auto-update, która automatyzuje proces budowy dokumentacji Sphinxa po każdym commicie^[11]. Projekt sponsorowany jest m.in. przez: Python Software Foundation^[12], Django Software Foundation, Mozilla Webdev^[13]. Przykładem projektu, który hostuje i udostępnia swoją dokumentację w serwisie Read the Docs jest biblioteka mwlib, umożliwiająca tworzenie książki w oprogramowaniu MediaWiki.

Zależności

Przed zainstalowaniem systemu Sphinx należy spełnić warunki zależności z innymi modułami Pythona^[14]:

Tworzenie dokumentacji

System Sphinx dostarczany jest z wbudowanym skryptem sphinx-quickstart, który po uruchomieniu zadaje użytkownikowi pytania i na podstawie udzielonych odpowiedzi tworzy odpowiednie katalogi oraz domyślny plik konfiguracyjny conf.py^[15].

Domyślnie tworzone są następujące katalogi i pliki:

source: Folder dla plików źródłowych dokumentacji.
build: Folder dla generowanej dokumentacji.
index.rst: Główny plik źródłowy dokumentacji.
conf.py: Główny plik konfiguracyjny dokumentacji.

Dokumentację generuje się przy pomocy polecenia sphinx-build, przykładowo:

$ sphinx-build -b html sourcedir builddir

lub – dla ułatwienia – za pośrednictwem skryptu Makefile lub make.bat, przykładowo:

$ make html

Powyższe skrypty są dostępne o ile wcześniej, podczas uruchomienia skryptu sphinx-quickstart użytkownik twierdząco odpowiedział na zadane pytanie:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. ‘make html’ instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]: y
> Create Windows command file? (Y/n) [y]: y

Przypisy

↑ Introduction – Sphinx 1.1.3 documentation. [dostęp 2012-09-01]. [zarchiwizowane z tego adresu (2012-09-09)]. (ang.).
↑ Available builders – Sphinx 1.1.3 documentation. [dostęp 2012-09-01]. [zarchiwizowane z tego adresu (2012-09-01)]. (ang.).
↑ Alfredo Deza: Easy and beautiful documentation with Sphinx. Making documentation effective and writable.. developerWorks, 2011-09-29. [dostęp 2012-09-02]. (ang.).
↑ Changes in Sphinx – Sphinx 1.1.3 documentation. [dostęp 2012-09-01]. [zarchiwizowane z tego adresu (2012-09-01)]. (ang.).
↑ About these documents – Python v2.7.3 documentation. [dostęp 2012-09-01]. Cytat: These documents are generated from reStructuredText sources by Sphinx, a document processor specifically written for the Python documentation. (ang.).
↑ New Documentation Format: reStructuredText Using Sphinx. [w:] Python v2.7.3 documentation (docs.python.org) [on-line]. [dostęp 2012-09-01]. (ang.).
↑ Projects using Sphinx – Sphinx 1.1.3 documentation. [dostęp 2012-09-01]. [zarchiwizowane z tego adresu (2012-09-15)]. (ang.).
↑ Homepages and other non-documentation sites. [w:] Projects using Sphinx [on-line]. [dostęp 2012-09-02]. [zarchiwizowane z tego adresu (2012-09-15)]. (ang.).
↑ Books produced using Sphinx. [w:] Projects using Sphinx [on-line]. [dostęp 2012-09-02]. [zarchiwizowane z tego adresu (2012-09-15)]. (ang.).
↑ Announcing Read The Docs. [dostęp 2012-09-02]. (ang.).
↑ Read the Docs features. [dostęp 2012-09-02]. (ang.).
↑ PSF Funds readthedocs.org. [w:] Python Software Foundation News [on-line]. Python Software Foundation. [dostęp 2012-09-02]. (ang.).
↑ Let’s write some docs – Mozilla Webdev. [dostęp 2012-09-02]. (ang.).
↑ Źródło: Sphinx-1.1.3-py2.7.egg/EGG-INFO/requires.txt.
↑ First Steps with Sphinx – Sphinx 1.1.3 documentation. [dostęp 2012-09-02]. [zarchiwizowane z tego adresu (2012-09-01)]. (ang.).

Linki zewnętrzne

Oficjalna strona systemu Sphinx
Lista projektów korzystających ze Sphinxa
Dokumentacja Pythona (wygenerowana z użyciem systemu Sphinx)

[1] Introduction – Sphinx 1.1.3 documentation. [dostęp 2012-09-01]. [zarchiwizowane z tego adresu (2012-09-09)]. (ang.).

[2] Available builders – Sphinx 1.1.3 documentation. [dostęp 2012-09-01]. [zarchiwizowane z tego adresu (2012-09-01)]. (ang.).

[3] Alfredo Deza: Easy and beautiful documentation with Sphinx. Making documentation effective and writable.. developerWorks, 2011-09-29. [dostęp 2012-09-02]. (ang.).

[4] Changes in Sphinx – Sphinx 1.1.3 documentation. [dostęp 2012-09-01]. [zarchiwizowane z tego adresu (2012-09-01)]. (ang.).

[5] About these documents – Python v2.7.3 documentation. [dostęp 2012-09-01]. Cytat: These documents are generated from reStructuredText sources by Sphinx, a document processor specifically written for the Python documentation. (ang.).

[6] New Documentation Format: reStructuredText Using Sphinx. [w:] Python v2.7.3 documentation (docs.python.org) [on-line]. [dostęp 2012-09-01]. (ang.).

[7] Projects using Sphinx – Sphinx 1.1.3 documentation. [dostęp 2012-09-01]. [zarchiwizowane z tego adresu (2012-09-15)]. (ang.).

[8] Homepages and other non-documentation sites. [w:] Projects using Sphinx [on-line]. [dostęp 2012-09-02]. [zarchiwizowane z tego adresu (2012-09-15)]. (ang.).

[9] Books produced using Sphinx. [w:] Projects using Sphinx [on-line]. [dostęp 2012-09-02]. [zarchiwizowane z tego adresu (2012-09-15)]. (ang.).

[10] Announcing Read The Docs. [dostęp 2012-09-02]. (ang.).

[11] Read the Docs features. [dostęp 2012-09-02]. (ang.).

[12] PSF Funds readthedocs.org. [w:] Python Software Foundation News [on-line]. Python Software Foundation. [dostęp 2012-09-02]. (ang.).

[13] Let’s write some docs – Mozilla Webdev. [dostęp 2012-09-02]. (ang.).

[14] Źródło: Sphinx-1.1.3-py2.7.egg/EGG-INFO/requires.txt.

[spx-tut-15] First Steps with Sphinx – Sphinx 1.1.3 documentation. [dostęp 2012-09-02]. [zarchiwizowane z tego adresu (2012-09-01)]. (ang.).

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

[14]

[15]