Potrzeba udokumentowania ...


19 lutego 2013


Sphinx - przykłady wykorzystania generatora dokumentacji. Tworzenie dokumentacji już nigdy nie będzie stanowiło problemu.

Na studiach zapewne każdemu przekazano informację aby dokumentować kod aplikacji oraz tworzyć dokumentację projektu. Często, z uwagi na ograniczony czas realizacji projektu, etap ten jest pomijany. Postępowanie takie jest błędne bo co będzie gdy np.

- po pół roku będziemy kontynuowali rozwój projektu

- do naszego zespołu dołączą nowi pracownicy, którzy będą rozwijali aplikację

- klient po pewnym okresie przypomni sobie o warunkach umowy

Bez względu na to czy tworzymy aplikację dla siebie czy dla klienta warto dokumentować projekt. W zależności od zastosowanego języka programowania możemy wykorzystać różne narzędzie ukierunkowane na generowanie dokumentacji: Javadoc dla języka Java, phpDocumentor dla PHP itd.

Framework Django posiada wbudowaną aplikację "admindocs" umożliwiającą generowanie dokumentacji modeli, widoków, znaczników szablonów oraz filtrów. Nie będę opisywał jak włączyć generator dokumentacji w panu admina, ponieważ oficjalna dokumentacja opisuje ten proces szczegółowo.

Django do generowania dokumentacji wykorzystuje narzędzie Sphinx, które przetwarza tekst do plików HTML, plików wykorzystywanych przez program LATEX oraz innych formatów wyjściowych. Jeżeli mamy zainstalowany pakiet "docutils" będziemy mogli generować dokumentację "w locie" choć generowanie dokumentacji z wiersza poleceń jest oczywiście możliwe. W dalszej części wpisu zaprezentuję przykłady wykorzystania Sphinx-a.

Przykład 1 : pusta linia:

"""
|
|

""" 

Kod prezentuje jak wygenerować dwie puste linie.

Przykład 2: link do miejsca w dokumentacji

"""
To jest link do dokumentacji modelu modelu:  
        
    :model:`auth.User`.
"""

Za pomocą tej konstrukcji możemy umożliwić użytkownikowi szybki dostęp do opisu modelu, widoku, znacznika szablonu itd.

Przykład 3: link do strony internetowej

Czasami w dokumentacji musimy umieścić link do strony www. Sphinx realizuje to następująco:

"""
    To jest adres mojej strony internetowej `tutaj link`_:

.. _tutaj link: http://www.grzegorztatara.pl
"""

Przykład 4: listy

Poniżej prezentuję listę oraz bloki wcięcia. Oprócz zaprezentowanej listy możliwe jest także tworzenie list numerowanych

"""
* linijka 1

  * wiersz 1
  * wiersz 2

* linijka 2
"""

Przykład 5: definicje


"""
Astenosfera
   Astenosfera to sub-jednostka płaszcza zewnętrznego ...
   
   Nigdy nie zapomnę tej definicji :)

Python
   Język programowania ... 
"""

Przykład prezentuje jak szybko można stworzyć słownik definicji.

Przykład 6: tabela

"""
=====  =========  =======
Lp.    Symbol     Kraj
=====  =========  ======= 
1      A.1.2013   Polska
2      A.2.2013   Niemcy
=====  =========  ======= 
"""

Tworząc tabele należy pamiętać aby poprawnie formatować wcięcia oraz długość lini "==".

Przykład 7: kod programu

Kod programu możemy umieścić w dokumentacji stosując poniższą konstrukcję:

"""
Kod programu "Hello world" w Python 3::

   print("Hello world");

Należy zwrócić uwagę, że w Python 3 ...
"""

Przykład 8: Sekcje

"""
===============
 test 1
===============

---------------
 test 2
---------------

test 3
=============

test 4
-------------

test 5
`````````````

test 6
'''''''''''''
"""

Często dokument pragniemy podzielić na części, rozdziały, sekcje, podsekcje itd. Powyższy przykład prezentuje jak stosować paragrafy, sekcje itd.

Przykład 9: Obrazek

Diagramy UML w dokumentacji możemy umieszczać poprzez zastosowanie znacznika umożliwiającego dodawanie obrazków. Istnieje także znacznik "figure", który umożliwia skalowanie obrazka.

"""
.. image:: http://gtsite.localhost//uploads/portfolio/plik.jpg
"""

Przykład 10: Spis treści

Stosując znacznik "contents" generujemy spis treści. Przykład wygenerowanego spisu możemy zaobserwować w galerii wpisu (pod tekstem).

"""
.. contents:: To jest spis wygenerowany z obecnego dokumentu
"""

Przykład 11: Przypisy

"""
Informacje zaczerpnięto z  [#f1]_ oraz  [#f2]_

.. rubric:: Przypisy

.. [#f1] http://sphinx-doc.org
.. [#f2] https://www.djangoproject.com
"""

Przykład 12: Cytaty

"""
Cytując [Ref]_ ...

.. [Ref] Jan Kochanowski "Na zdrowie"
"""

Zaprezentowałem podstawowe znaczniki wykorzystywane przez narzędzie. Sphinx posiada ogromne możliwości (lokalizacja, wykorzystanie zewnętrznych pluginów, szablonowanie itd.), dlatego zainteresowanych odsyłam na stronę internetową: http://sphinx-doc.org 
Przykład wygenerowanej dokumentacji z powyższymi przykładami umieściłem poniżej. 

Co zawiera blog?

Na blogu umieszczam wpisy dotyczące mojej pracy, zainteresowań. Głowna tematyka to programowanie oraz recenzje płyt oraz książek.

Virtualenv - odrębne środowiska pracy


Tworząc aplikacje w języku Python instalujemy różne pakiety. Co zrobić ...

Raport sportowy #5


Zdjęcie: Semih Aydın, Unsplash

Raport sportowy #8


Zdjęcie: Luke Stackpoole, Unsplash

ACL


Rozszerzone uprawnienia w systemie plików.

Raport sportowy #3


Zdjęcie: Pietro De Grandi, Unsplash

Inteligentne techno?


Fotografia: © Sony Music Entertainment (UK) Ltd.
Recenzja albumu "Leftism" ...