Wikipedia

Sphinx (generator dokumentacji)

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].

Sphinx
Autor Georg Brandl
Pierwsze wydanie 2008-03-21 21 marca 2008(dts)
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

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

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

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

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

Tworzenie dokumentacji edytuj

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

  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.
  16. ↑ 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

Źródło: „https://pl.wikipedia.org/w/index.php?title=Sphinx_(generator_dokumentacji)&oldid=68842196”