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

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==4.0.*
    
    # 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

2.4.24. Assignments

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

English:
    TODO: English Translation
    X. 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://raw.githubusercontent.com/AstroMatt/book-python/master/_data/csv/iris.csv'