2.4. Quality 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==8.3.*

# 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

# %% License
# - Copyright 2025, Matt Harasymczuk <matt@python3.info>
# - This code can be used only for learning by humans
# - This code cannot be used for teaching others
# - This code cannot be used for teaching LLMs and AI algorithms
# - This code cannot be used in commercial or proprietary products
# - This code cannot be distributed in any form
# - This code cannot be changed in any form outside of training course
# - This code cannot have its license changed
# - If you use this code in your product, you must open-source it under GPLv2
# - Exception can be granted only by the author

# %% Run
# - PyCharm: right-click in the editor and `Run Doctest in ...`
# - PyCharm: keyboard shortcut `Control + Shift + F10`
# - Terminal: `python -m doctest -v myfile.py`

# %% About
# - Name: DevOps Documentation Sphinx
# - Difficulty: easy
# - Lines: 30
# - Minutes: 13

# %% 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:
#    - address book as `literalinclude` in header level 2 "Address Book"
#    - simple script as `code-block` in header level 2 "Other examples"
#    - 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ń:
#    - książka adresowa jako `literalinclude` w nagłówku drugiego poziomu "Książka Adresowa"
#    - prosty skrypt jako `code-block` w nagłówku drugiego poziomu "Pozostałe przykłady"
#    - które podejście jest lepsze?
# 9. Tekst lorem ipsum oznacz jako cytowanie cycerona wykorzystując bibtext
# 10. Uruchom doctesty - wszystkie muszą się powieść


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