Sphinx (generator dokumentacji)

Z Wikipedii, wolnej encyklopedii
Skocz do: nawigacji, wyszukiwania
Sphinx
Generator dokumentacji
Producent Georg Brandl
Platforma sprzętowa Wieloplatformowy
System operacyjny Wielosystemowy
Napisane w Python
Pierwsze wydanie 2008-03-2121 marca 2008
Aktualna wersja stabilna 1.1.3 (2012-03-10)
Aktualna wersja testowa 1.2
Licencja BSD
sphinx.pocoo.org

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[edytuj | edytuj kod]

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[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[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[edytuj | edytuj kod]

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

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[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

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

Linki zewnętrzne[edytuj | edytuj kod]