Tworzenie dokumentacji projektowej z Read the Docs

Tworząc projekt open source w pewnym momencie przychodzi czas, w którym należałoby nasze dzieło udokumentować celem jego zrozumienia przez innych programsitów. Dostawcy usług jak GitHub czy Bitbucket oferują wbudowane mechnizmy jak popularne Wiki, jednak według mnie posiadają one kilka zasadniczych minusów:

  • Wiki jest nierozłączną częscią repozytorium projektu (choć można zrobić niezależny clone).
  • Wiki nie jest (jawnie) wersjonowane. Wgląd w kolejne rewizje jest możliwy, ale nie mamy mozliwości np. utworzenia gałęzi w GIT i rozwijania na niej nowych fragmentów dokumentacji.
  • Nie istnieje wbudowany mechnizm eksportu wiki (w formie zagregowanej) do pliku np. PDF.

 

Oczywiście powyższe „minusy” nie są krytyczne jeśli chodzi o ogólne użytkownie i być może dla Ciebie nie są w ogóle problemem. Pozwól jednak, że przedstawię Ci alternatywne narzędzie, które być może przypadnie Ci do gustu. Nazywa się Read the Docs.

 

Co to jest Red the Docs?

W telegraficznym skrócie Read the Docs (później w tekście RtD) to niezależny, darmowy hosting dla dokumentacji. Jego kluczowe cechy to:

  • możliwość odseparowania kodu dokumentacji od kodu projektu
  • automatyczna synchronizacja dokumentacji z jej kodem (np. umieszczonym na GitHub) poprzez webhooki
  • obłsuga wielu wersji dokumentacji
  • łatwy eksport do popularnych rozszerzeń jak np. PDF, HTML, Epub

RtD obsługuje dwa rodzaje plików dokumentacji. Domyslnym jest *.rst (reStructuredText), który jest zapewne dobrze znany programistom Pythin. Drugi, w mojej ocenie prostrzy to *.md czyli Markdown. Z uwagi na prostotę konfiguracji i popularność Markdown, to własnie tę „opcje” wybiorę do skonfigurowania naszej dokumentacji.

 

Integracja z RtD – część lokalna

Aby móc stowrzyć naszą dokumentację w pierszej kolejności stwórz dla niej repozytorium u dowolnego dostawcy usług jak GitHub, BitBucket czy GitLab. Gdy uda Ci się to zrobić, sklonuj repozytorium na lokalną maszynę.
Do kolejnych kroków niezbędnę będzie zainstalowanie Pythona, który udostępnia swój menedżer pakietów o nazwie PIP. Pythona (w wersji 3.7.1) na swój OS pobierzesz za darmo tutaj. Po zakończeniu instalacji otwórz konsolę i przejdź do katalogu ze świeżo sklonowanym repozytorium dokumentacji. Następnie wykonaj polecenie:

 


py -m pip install mkdocs

 

Powyższa komenda rozpocznie pobieranie MkDocs czyli prostego generatora dokumentacji w Markdown. Po chwili narzędzie powinno zostać zainstalowane globalnie na Twojej maszynie. Będąc w katalogu repozytorium wygeneruj nową dokumentację przy uzyciu komendy:

 


py -m mkdocs new .

 

W rezultacie Twoja dokumentacja powinna składać się z:

  • mkdocs.yml – plik konfiguracyjny dokumentacji
  • docs/index.md – strona główna dokumentacji

 

Aby wyhostować dokumentację lokalnie z automatycznym obserwowaniem zmina w plikach wykonaj polecenie:

 


py -m mkdocs serve

 

Po chwili dokumentacja powinna być dostepna pod localhost:8000:

 

 

Przed przejściem dalej wykonaj jeszcze drobny zabieg kosmetyczny. Przejdź do pliku mkdocs.yml, a następnie dokonaj dwóch zmian: zmień nazwę swojej dokumentacji na nazwę np. projektu, a ponadto zmień motyw dokumentacji na domyslny motyw RtD (dodaj kolejny wiersz – theme: readthedocs). Dokumentacja powinna odświeżyć się automatycznie:

 

 

Zwróć uwagę, że sam motyw na podstawie paragrafów w tekście stworzył czytelną strukturę nawigacyjną po lewej stronie co znacznie ułatwie korzystanie z dokumentacji.

Samej składni Markdown nie będę tłumaczyl w tym wpisie. Jeżeli nie jesteś z nią zaznajomiony to polecam darmowe narzędzie online o nazwie Dillinger. Znajdziesz w nim edytor z podglądem na żywo jak i wszelkie przykłady użyc np. tabel, linków, pogrubień, listingów itp. Jedyną kwestią, którą warto jeszcze poruszyć to rozbudowa dokumentacji o kolejne sekcje. W tym celu jedyne co musisz zrobić to w katalogu docs dodać kolejny plik Markdown. Ja przykładowo dodałem plik getting-started.md, którego treść wygląda następująco:

 

## How to run the code?
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus consectetur dui a quam congue faucibus. Ut nibh augue, maximus quis nibh quis, faucibus varius ante.

## How to run unit tests?
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus consectetur dui a quam congue faucibus. Ut nibh augue, maximus quis nibh quis, faucibus varius ante.

## How to attach to the application?
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus consectetur dui a quam congue faucibus. Ut nibh augue, maximus quis nibh quis, faucibus varius ante.

Po zapisaniu pliku zmiany prezentują się następująco:

 

 

Gdy Twoja dokumentacja będzie kompletna jedyne co pozstaje zrobić to commit & push.

 

Integracja z RtD – część hostingowa

W pierwszym kroku udaj sie na adres readthedocs.org i załóż konto. Po zalogowaniu przejdź do sekcji My Projects -> Import Repository. Repozytorium z dokumentacją możesz wskazać dwojako, albo łącząc się z konkretnym dostawcą, albo robiąc to ręcznie. W związku z tym, że pierwsza opcja sprowadza się jedynie do kilku kliknięc pozwolę sobie na zaprezentowanie drugiego sposobu.

W pierwszym kroku uzupełniamy dane zgodnie z formatką:

 

 

Ważne jest, aby w polu URL podać po prostu adres repozytorium, a nie adres dla GIT-a. Po kliknieciu przycisku Next  znajdziesz się na stronie projektu. Przejdź następnie do Admin->Integrations->Add integration. Wybierz odpowiedni incoming webhook (w moim przypadku GitHub), a następnie skopiuj wygenerewoeny adres. Udaj się następnie do swojego repozytium z dokumentacją i dodaj integrację z otrzymanym webhookiem. W przypadku GitHuba jest to Repozytium projektu->Settings->Webhooks->Add webhook. Tak wyglądają poprawne ustawienia:

 

 

Kliknij Add webhook i voilà! Na tym kończy się róznica miedzy sposobem dodanie repozytorium do RtD.

Pozostaje jeszcze jedna, drobna zmiana. Jak wspomniałem na początku wpisu, RtD domyślnie obsługuje pliki *rst. Aby zmienić to na Markdown udaj się na do Admin-> Settings->Documentation type i zmień wybór na MkDocs (Markdown). Po zapisaniu zmian projekt powinien się poprawnie zbudować co zauważysz przechodząc do zakładki Builds:

 

 

Kliknij w zielony przycisk View docs,a twoim oczom powinna ukazać się dokumentacja. Tym razem będzie ona publicznie dostępna 🙂

 

 

Zwróć uwagę, że bez dodatkowej konfiguracji masz mozliwość zapisania dokumentacji do wcześniej wymienionych formatów plików. Posidasz także wgląd w wersję dokumentacji, którą obecnie przeglądasz.

 

Wersjonowanie

Wersjonowanie dokumentacji jest bardzo proste. Domyślnie przyjętą „strategią” wersjonowania jest zwykłe utworzenie gałęzi i wypchnięcie jej do repozytrium. Drugą opcją są tagi. Jeżeli w repozytorium pojawi się jakikolwiek tag to strategia automatycznie przestawi się na ten własnie wersjonowania. Zobaczmy jak działa to w praktyce. Będą konsolą w repozytorium utworzę gałąź o nazwie 2.0.0:

 


git checkout -b 2.0.0

 

Nastepnie dokonam zmiany w pliku index.md i zrobię commit & push. Po chwili moja wersja powinna byc widoczna w RtD. Wgląd odbywa się przez widok Versions. Domyslnie każda nowa wersja nie jest publicznie dostępna i znajduje się w tabeli Inactive versions:

 

 

Aby to zmienic przejdź do Edit i zaznacz checkbox Active. Po zapisaniu zmian będzie publicznie ona  dostępna, a użytkownicy będą mieli mozliwość dynamicznie przełączać się między wersjami.

 

To tyle na dziś. Daj znać co sądzisz o RtD! Czy jest to narzędzie, które będziesz używac w przyszłości, czy stare dobre Wiki jest nadal lepszą opcją 😉 ?