Sphinx (generator dokumentacji) – Wikipedia, wolna encyklopedia
Autor | Georg Brandl |
---|---|
Pierwsze wydanie | (dts) | 21 marca 2008
Aktualna wersja stabilna | 3.3.0 (2 listopada 2020; ponad 3 lata temu)[1] |
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
[edytuj | edytuj kod]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
[edytuj | edytuj kod]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
[edytuj | edytuj kod]Przed zainstalowaniem systemu Sphinx należy spełnić warunki zależności z innymi modułami Pythona[15]:
Tworzenie dokumentacji
[edytuj | edytuj kod]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
[edytuj | edytuj kod]- ↑ 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
[edytuj | edytuj kod]- Oficjalna strona systemu Sphinx
- Lista projektów korzystających ze Sphinxa
- Dokumentacja Pythona (wygenerowana z użyciem systemu Sphinx)