1.4. ReST and Sphinx documentation

1.4.1. reStructuredText vs. Markdown

1.4.2. Format reStructuredText

1.4.2.1. Po co?

1.4.2.2. Paragrafy

  • newline

1.4.2.3. Nagłówki

  • Tytuł

  • Nagłówek pierwszego poziomu

  • Nagłówek drugiego poziomu

  • Nagłówek trzeciego poziomu

  • Nagłówek czwartego poziomu (czy stosować?)

1.4.2.4. Odnośniki

  • Wewnątrz dokumentu

  • numref

  • na zewnątrz dokumentu

1.4.2.5. Obrazki i media

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

1.4.2.6. Specjalne wstawki

  • .. todo::

1.4.2.7. Listingi kodu

  • Osadzone

  • Z plików zewnętrznych

1.4.2.8. TODO

1.4.2.9. Listy

  • listy nieuporządkowane

  • listy numerowane

  • jednopoziomowe i zagnieżdżone

  • listy mieszane

1.4.2.10. Tabele

  • Table

  • List Table

  • CSV Table

1.4.2.11. Cytowanie

  • cite

  • bibtex

1.4.3. Sphinx

1.4.3.1. Zależności

  • requirements.txt

    # Minimalne wymaganie
    sphinx==3.2.*
    
    # Theme Read the Docs
    sphinx_rtd_theme
    
    # System cytowania i parsowanie bibtex
    sphinxcontrib-bibtex
    
    # Jeżeli chcemy generować slajdy RevealJS
    sphinxjp.themes.revealjs
    

1.4.3.2. Config

  • Wersja na podstawie hasha git

1.4.3.3. 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

1.4.3.4. Generowanie dokumentacji

  • Table of Contents

1.4.3.5. toctree

1.4.3.6. Automatyczne odpalanie doctestów do listingów kodu

1.4.3.7. Osadzanie LaTeX

1.4.3.8. Budowanie

  • make html

  • make singlehtml

  • make pdf

  • generowanie Word (docx) -> pandoc

1.4.4. Read the docs

1.4.5. Assignments

1.4.5.1. Dokumentacja

  • Assignment: Dokumentacja

  • Last update: 2020-10-01

  • Complexity level: easy

  • Lines of code to write: 30 lines

  • Estimated time of completion: 13 min

  • Filename: TODO

English:

Todo

English Translation

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

Given:
DATA = 'https://raw.githubusercontent.com/AstroMatt/book-python/master/_data/csv/iris.csv'