Sphinx – system tworzenia i generowania dokumentacji technicznej, który konwertuje pliki źródłowe reStructuredText najczęściej do dokumentu HTML, ale możliwe jest również określenie innych formatów wyjściowych, np.: LaTeX, PDF, ePUB, man.
Zastosowanie zwykłego tekstu () 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 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.
Zarys historii Pierwsza, publiczna wersja systemu o numerze 0.1.61611 została wydana 21 marca 2008 r. System został opracowany specjalnie na potrzeby tworzenia dokumentacji dla języka programowania Python. 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.
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.
Poza tworzeniem dokumentacji, system Sphinx został wykorzystany do budowy stron internetowych. Może też być wykorzystywany do składu i przygotowywania książek do druku.
W celu łatwiejszego zarządzania stworzoną dokumentacją, w kwietniu 2010 r. utworzony został projekt Read the Docs. 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. Projekt sponsorowany jest m.in. przez: Python Software Foundation, Django Software Foundation, Mozilla Webdev. 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Źródło: Sphinx-1.1.3-py2.7.egg/EGG-INFO/requires.txt.: Pygments (PyPI) Jinja2 (PyPI) docutils (PyPI)
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.
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 , przykładowo: $ sphinx-build -b html sourcedir builddir lub – dla ułatwienia – za pośrednictwem skryptu lub , przykładowo: $ make html
Powyższe skrypty są dostępne o ile wcześniej, podczas uruchomienia skryptu , 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
Linki zewnętrzne Oficjalna strona systemu Sphinx Lista projektów korzystających ze Sphinxa Dokumentacja Pythona (wygenerowana z użyciem systemu Sphinx)
Kategoria:Oprogramowanie na licencji BSD Kategoria:Generatory dokumentacji Kategoria:Wolne oprogramowanie napisane w Pythonie