Prosty samouczek na temat dokumentowania projektu Python za pomocą Sphinx i Rinohtype

Dokumentowanie kodu jest jednym z zadań, których tak naprawdę nie chcę robić, ale i tak zrobię to dla ocen.

To prawdopodobnie usłyszysz ode mnie, gdy byłem studentem pierwszego roku informatyki. Dokumentowanie kodu jest nudne i bezużyteczne, ponieważ już wiem, co robi mój kod, a jedyną osobą, która prawdopodobnie go przeczyta, jest profesor sprawdzający go.

Nie zrozumiałem jego znaczenia, aż któregoś dnia, musiałem przyjrzeć się temu nieudokumentowanemu kodowi, który napisałem lata temu w celach informacyjnych, a zamiast po prostu go przeglądać, spędziłem sporo czasu, będąc dość zdezorientowany co do struktury projektu, a nawet jak to uruchomić.

Obecnie dostępnych jest wiele narzędzi, które pomagają nam w dokumentowaniu kodu. Ostatnio dowiedziałem się o narzędziach, które ułatwiają tworzenie inteligentnej i pięknej dokumentacji. Dwa z nich to Sfinks i Rinohtype.

Sphinx, napisany przez Georga Brandla i licencjonowany na licencji BSD, został pierwotnie stworzony do dokumentacji Pythona i ma doskonałe możliwości dokumentacji projektów oprogramowania w różnych językach (Sphinx-doc.org, 2018).

Rinohtype w połączeniu ze Sphinx oferuje nowoczesną alternatywę dla LaTeX. Zapewnia backend Sphinx, który pozwala generować profesjonalnie składane dokumenty PDF (Machiels).

W tym samouczku będę używać Sphinx i Rinohtype do tworzenia plików dokumentacji HTML i PDF odpowiednio do prostego projektu API, który napisałem i który zarządza listą rekordów Nauczyciela (Github Project Link).

  1. Sklonuj projekt i usuń / przenieś folder dokumentów, abyś mógł śledzić mnie podczas tworzenia nowej dokumentacji.
  2. Przejdź do katalogu głównego projektu.
  3. Utwórz i aktywuj środowisko wirtualne Python 3
virtualenv -p python3 
source  / bin / aktywuj
Tutaj nazwałem wirtualne środowisko „venv”

4. Zainstaluj wszystkie wymagania projektu

pip install -r wymagania.txt

Uwaga: Sphinx i Rinohtype są już w pliku wymagania.txt. Jeśli chcesz zainstalować je w środowisku wirtualnym projektu, nad którym pracujesz, użyj poniższych poleceń.

pip zainstaluj Sphinx
pip install rinohtype

5. Utwórz katalog docs i cd do tego katalogu.

mkdir docs
dokumenty cd

6. Skonfiguruj Sfinksa

szybki start sfinksa
Postępuj zgodnie z tą konfiguracją na razie. Możesz zmienić to później samodzielnie.kontynuacja poprzedniego zdjęcia

7. Open source / conf.py

  • Skonfiguruj ścieżkę do katalogu głównego
Odkomentowanie linii 15–17Zmień ścieżkę na „../ ..” i dodaj sys.setrecursionlimit (1500)

Ścieżka powinna wskazywać na katalog główny projektu i patrząc na strukturę projektu, z conf.py powinniśmy dotrzeć do katalogu głównego, przechodząc do dwóch katalogów nadrzędnych.

Struktura projektu
  • Dodaj Rinohtype do listy rozszerzeń
„rinoh.frontend.sphinx”
  • Odkomentuj elementy lateksowe
odkomentuj teMożesz zmienić format dalej, są to tylko ustawienia domyślne.

8. Otwórz plik index.rst i zmień zawartość na następujące. (Kliknij link index.rst, aby uzyskać pełną treść)

Dokumentacja do Kodeksu
**************************
.. toctree ::
   : maxdepth: 2
   : podpis: Treść:

TeacherAPI główny
===================
.. automodule :: app
   : członkowie:

Kontroler TeacherAPI
=====================
.. automodule :: nauczycielAPI.controller
   : członkowie:

Modele TeacherAPI
=================
.. automodule :: teacherAPI.models
   : członkowie:

Baza danych TeacherAPI
===================
.. automodule :: nauczycielAPI.database
   : członkowie:

Nauczyciel zapełnij
===================
.. automodule :: teacherAPI.populate
   : członkowie:

9. Utwórz pliki dokumentacji HTML i PDF.

  • Wciąż działa katalog docs
zrób html
sphinx-build -b rinoh source _build / rinoh

EDYTUJ UWAGĘ [16 marca 2019 r.]: Kompilacja pliku pdf nie powiedzie się, jeśli Twoja wersja Pythona ma wersję ≥3.7.0 (numer wydania Github)

Pierwszy wiersz wygeneruje plik HTML w docs / build / html / index.html

Widok index.htmlWidok index.html

Drugi wiersz utworzyłby plik PDF w docs / _build / rinoh / SimpleTeacherDataAPI.pdf

Strona tytułowa dokumentacjiSpis treściPrzykładowa strona dokumentacji

Po doświadczeniu w projektach zespołowych zacząłem doceniać dokumentowanie kodu i chociaż nie powiedziałbym, że jest to najbardziej przyjemne zadanie, jest zdecydowanie niezawodne i powinno być praktykowane przez programistów .

Aby dowiedzieć się więcej o Sfinksie:

  • Przegląd - dokumentacja Sphinx 1.8.0+

Inne przydatne samouczki:

  • Dokumentowanie projektu za pomocą Sphinx - Pomogło mi to zrozumieć, jak dokumentować mój kod za pomocą dokumentów w języku Python.
  • Samouczek Sfinksa Brandona - obszerny samouczek korzystania ze sfinksa

Machiels, Brecht. „Rinohtype: The Python Document Processor - Rinohtype 0.3.1.Dev0 Documentation.” Rinohtype.readthedocs.io. N.p., 2016. Web. 17 czerwca 2018 r.

Sphinx-doc.org. (2018). Przegląd - dokumentacja Sphinx 1.8.0+. [online] Dostępny pod adresem: http://www.sphinx-doc.org/en/master/ [Dostęp 17 czerwca 2018 r.].