2.4. ReST and Sphinx documentation¶

2.4.1. reStructuredText vs. Markdown¶

2.4.2. Format reStructuredText¶

2.4.3. Po co?¶

2.4.4. Paragrafy¶

newline

2.4.5. Nagłówki¶

Tytuł
Nagłówek pierwszego poziomu
Nagłówek drugiego poziomu
Nagłówek trzeciego poziomu
Nagłówek czwartego poziomu (czy stosować?)
https://devguide.python.org/documenting/#sections

2.4.6. Odnośniki¶

Wewnątrz dokumentu
numref
na zewnątrz dokumentu

2.4.7. Obrazki i media¶

figure (scale, name, align, podpisy pod obrazkami)

2.4.8. Specjalne wstawki¶

.. todo::

2.4.9. Listingi kodu¶

Osadzone
Z plików zewnętrznych

2.4.10. TODO¶

2.4.11. Listy¶

listy nieuporządkowane
listy numerowane
jednopoziomowe i zagnieżdżone
listy mieszane

2.4.12. Tabele¶

Table
List Table
CSV Table

2.4.13. Cytowanie¶

cite
bibtex

2.4.14. Sphinx¶

2.4.15. Zależności¶

requirements.txt

# Minimalne wymaganie
sphinx==7.2.*

# Theme Read the Docs
sphinx_rtd_theme

# System cytowania i parsowanie bibtex
sphinxcontrib-bibtex

# Jeżeli chcemy generować slajdy RevealJS
sphinxjp.themes.revealjs

2.4.16. Config¶

Wersja na podstawie hasha git

2.4.17. Dobre praktyki¶

podział na rozdziały
rozkład katalogów
listingi kodu
zdjęcia
dane w tabelkach CSV
konwencja nazewnicza plików
konwencja nazewnicza figure, csv-table, literalinclude

2.4.18. Generowanie dokumentacji¶

Table of Contents

2.4.19. toctree¶

2.4.20. Automatyczne odpalanie doctestów do listingów kodu¶

2.4.21. Osadzanie LaTeX¶

2.4.22. Budowanie¶

make html
make singlehtml
make pdf
generowanie Word (docx) -> pandoc

2.4.23. Read the docs¶

http://readthedocs.org

2.4.24. Assignments¶

Code 2.26. Solution¶

"""
* Assignment: DevOps Documentation Sphinx
* Complexity: easy
* Lines of code: 30 lines
* Time: 13 min

English:
    1. Using `sphinx-quickstart` create documentation.
    2. Change theme to `sphinx_rtd_theme`
    3. Title document "Python Training"
    4. Create header level 1 "Images and text" and embed image as figure, with text description, image should be half size and centered, named
    5. Create header level 1 "Lorem Ipsum" and paste lorem ipsum text to documentation.
    6. In lorem ipsum text insert numref to image
    7. Create header level 1 and place Iris table based on Iris Dataset
    8. Create header level 1 "Code listings" and embed two your scripts from previous assignments:
        a. address book as `literalinclude` in header level 2 "Address Book"
        b. simple script as `code-block` in header level 2 "Other examples"
        c. which approach is better?
    9. Lorem ipsum text mark as Cicero quote using bibtext
    10. Run doctests - all must succeed

Polish:
    1. Za pomocą `sphinx-quickstart` stwórz dokumentację.
    2. Zmień theme na `sphinx_rtd_theme`
    3. Dokument zatytułuj "Szkolenie z Pythona"
    4. Stwórz nagłówek pierwszego poziomu "Obrazki i teksty" i w nim osadź obrazek jako figure, wraz tekstem opisującym, obrazek ma być połowy wielkości i wycentrowany, nazwany
    5. Stwórz nagłówek pierwszego poziomu "Lorem Ipsum" i wklej tekst lorem ipsum do dokumentacji.
    6. W tekście lorem ipsum wstaw numref do obrazka
    7. Stwórz nagłówek pierwszego poziomu i zamieść tabelę Irysów na podstawie danych Iris Dataset
    8. Stwórz nagłówek pierwszego poziomu "Listingi kodu" i osadź dwa swoje skrypty z poprzednich zadań:
        a. książka adresowa jako `literalinclude` w nagłówku drugiego poziomu "Książka Adresowa"
        b. prosty skrypt jako `code-block` w nagłówku drugiego poziomu "Pozostałe przykłady"
        c. które podejście jest lepsze?
    9. Tekst lorem ipsum oznacz jako cytowanie cycerona wykorzystując bibtext
    10. Uruchom doctesty - wszystkie muszą się powieść
"""

DATA = 'https://python3.info/_static/iris.csv'