14. Tworzenie dokumentacji

14.1. reStructuredText vs. Markdown

14.2. Format reStructuredText

14.2.1. Po co?

14.2.2. Paragrafy

  • newline

14.2.3. Nagłówki

  • Tytuł
  • Nagłówek pierwszego poziomu
  • Nagłówek drugiego poziomu
  • Nagłówek trzeciego poziomu
  • Nagłówek czwartego poziomu (czy stosować?)

14.2.4. Odnośniki

  • Wewnątrz dokumentu
  • numref
  • na zewnątrz dokumentu

14.2.5. Obrazki i media

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

14.2.6. Specjalne wstawki

  • .. todo::

14.2.7. Listingi kodu

  • Osadzone
  • Z plików zewnętrznych

14.2.8. TODO

14.2.9. Listy

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

14.2.10. Tabele

  • Table
  • List Table
  • CSV Table

14.2.11. Cytowanie

  • cite
  • bibtex

14.3. Sphinx

14.3.1. Zależnośći

# Minimalne wymaganie
sphinx==1.8.0

# Theme Read the Docs
sphinx_rtd_theme

# System cytowania i parsowanie bibtex
sphinxcontrib-bibtex==0.3.6

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

14.3.2. Config

  • Wersja na podstawie hasha git

14.3.3. Dobre praktyki

  • podział na rozdziały
  • rozkład katalogów
  • listingi kodu
  • zdjecia
  • dane w tabelkach CSV
  • konwencja nazewnicza plikow
  • konwencja nazewnicza figure, csv-table, literalinclude

14.3.4. Generowanie dokumentacji

  • Table of Contents

14.3.5. toctree

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

14.3.7. Osadzanie LaTeX

14.3.8. Buildery

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

14.4. Read the docs

14.5. Zadania kontrolne

14.5.1. Dokumentacja

  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 tesksy” 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 https://raw.githubusercontent.com/scikit-learn/scikit-learn/master/sklearn/datasets/data/iris.csv

  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

Podpowiedź:
  • sphinxcontrib-bibtex==0.3.6