Sphinx - system dokumentacji dla Pythona (1/24) Sphinx - system dokumentacji dla Pythona Michał Jaworski
docstrings Sphinx - system dokumentacji dla Pythona (2/24)
docstrings Sphinx - system dokumentacji dla Pythona (3/24) def max(a, b): """ Funkcja zwracająca większą z dwóch liczb """ if (a>b): return a else: return b >>> print max. doc Funkcja zwracająca większą z dwóch liczb
docstrings c.d. Sphinx - system dokumentacji dla Pythona (4/24) class Misiek: _zyw = None "opisuje czy misiek jest żywy" def init (self): """Inicjalizator miśka - tworzy i ożywia""" self._zyw = True print "misiek żyw!" # komunikat o stworzeniu >>> print Misiek. init. doc Konstruktor miśka - tworzy i ożywia
dostęp do docstrings python: >>> print object. doc >>> help(object) ipython: >>> object? >>> object?? powłoka: $ pydoc object Sphinx - system dokumentacji dla Pythona (5/24)
Sphinx - system dokumentacji dla Pythona (6/24) rest - restructuredtext
rest - restructuredtext Opis tego slajdu: RST - restructuredtext ---------------------- Opis tego slajdu: :: (...) Sphinx - system dokumentacji dla Pythona (7/24)
rest - podstawowe znaczniki Rozdział ======== Sekcja ------ Podsekcja ~~~~~~~~~ *kursywa* **pogrubienie**.. code-block:: język Sphinx - system dokumentacji dla Pythona (8/24)
Sphinx - system dokumentacji dla Pythona (9/24) rest - podstawowe znaczniki c.d... image:: pic/python.png
rest - podstawowe znaczniki c.d. #) Numerowana lista #) Drugi element a) Podelement #) Trzeci element Sphinx - system dokumentacji dla Pythona (10/24) 1. Numerowana lista 2. Drugi element a. Podelement 3. Trzeci element
Sphinx - system dokumentacji dla Pythona (11/24) rest - pozostałe znaczniki nienumerowane listy tabele odnośniki i wiele innych... Źródła: http://docutils.sourceforge.net/docs/user/rst/quickstart.html http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt
Sphinx Zalety: restructuredtext docstrings elastyczny estetyczny Sphinx - system dokumentacji dla Pythona (12/24)
Sphinx - system dokumentacji dla Pythona (13/24) Sphinx - instalacja Debian/Ubuntu: $ sudo apt-get install python-sphinx EasyInstall: $ easy_install -U Sphinx
Sphinx - system dokumentacji dla Pythona (14/24) Sphinx - tworzenie dokumentacji $ sphinx-quickstart Domyślnie: source folder ze źródłami dokumentacji build folder z wygenerowaną dokumentacją index.rst główny plik źródłowy dokumentacji conf.py plik konfiguracyjny dokumentacji
Sphinx - index.rst Welcome to test's documentation! ================================ Zawartość:.. toctree:: :maxdepth: 2 wstep moduly Sphinx - system dokumentacji dla Pythona (15/24)
Sphinx - index.rst c.d. Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` Sphinx - system dokumentacji dla Pythona (16/24)
Sphinx - wstep.rst Wstęp ===== Tutaj treść wstępu. Sphinx - system dokumentacji dla Pythona (17/24)
Sphinx - moduly.rst Struktura projektu ================== Sphinx - system dokumentacji dla Pythona (18/24) Spis modułów dostępnych w projekcie. Moduły ------.. automodule:: prezentacja :members:
Generowanie dokumentacji do html: $ make html do pdf (dzięki latex'owi) $ make latex $ cd build/latex $ make Sphinx - system dokumentacji dla Pythona (19/24)
Sphinx - system dokumentacji dla Pythona (20/24) Sphinx - konfiguracja tematy graficzne "metadane" opcje generowania kodu html i latex obsługa rozszerzeń
Sphinx - rozszerzenia Przykładowa modyfikacja rozszerzenia autodoc: def automoduleskipcb(app, what, name, obj, skip, options): return False def setup(app): app.connect("autodoc-skip-member",automoduleskipcb) conf.py: Sphinx - system dokumentacji dla Pythona (21/24) extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx_change_automodule_skip' ]
Sphinx - system dokumentacji dla Pythona (22/24) Sphinx - wybrane rozszerzenia sphinx.ext.autodoc automatyczna dokumentacja dla modułów sphinx.ext.todo wsparcie dla list TODO sphinx.ext.graphviz grafy generowane za pomocą Graphviz sphinx.ext.inheritance_diagram diagramy dziedziczenia sphinx.ext.pngmath oraz sphinx.ext.jsmath renderowanie równań matematycznych
Sphinx - system dokumentacji dla Pythona (23/24) Inne narzędzia doxygen epydoc pydoc
Źródła Sphinx - system dokumentacji dla Pythona (24/24) http://sphinx.pocoo.org http://docs.python.org/documenting/index.html http://docutils.sourceforge.net/rst.html