Sphinx (generator dokumentacji) – Wikipedia, wolna encyklopedia

Sphinx
Autor	Georg Brandl
Pierwsze wydanie	21 marca 2008(dts)
Aktualna wersja stabilna	3.3.0 (2 listopada 2020; ponad 3 lata temu)
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^[2], ale możliwe jest również określenie innych formatów wyjściowych, np.: LaTeX, PDF, ePUB, man^[3].

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^[4].

Zarys historii

Pierwsza, publiczna wersja systemu o numerze 0.1.61611 została wydana 21 marca 2008 r.^[5]. System został opracowany specjalnie na potrzeby tworzenia dokumentacji dla języka programowania Python^[6]. 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^[7].

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^[8].

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

W celu łatwiejszego zarządzania stworzoną dokumentacją, w kwietniu 2010 r. utworzony został projekt Read the Docs^[11]. 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^[12]. Projekt sponsorowany jest m.in. przez: Python Software Foundation^[13], Django Software Foundation, Mozilla Webdev^[14]. 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^[15]:

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^[16].

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

↑ Changes in Sphinx — Sphinx 4.0.0+ documentation [online], www.sphinx-doc.org [dostęp 2020-11-12] (ang.).
↑ 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] Changes in Sphinx — Sphinx 4.0.0+ documentation [online], www.sphinx-doc.org [dostęp 2020-11-12] (ang.).

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

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

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

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

[6] 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.).

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

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

[9] 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.).

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

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

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

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

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

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

[spx-tut-16] 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]

[16]