Odcinek 16 - Generowanie dokumentacji z kodu źródłowego
Jak można ulepszyć lub uprościć tworzenie dokumentacji ? Jak zadbać o aktualność danych zawartych w dokumentacji ? Na te pytania odpowiem w odcinku, a materiały znajdziesz na https://github.com/sebastianczech/podcast-everything-as-a-code/tree/main/episode-016.
A w Terraformie mamy Terraforum Docs. Jak więc widzisz, dla wymienionych przeze mnie przykładowych języków tych narzędzi jest sporo. Linki do tych narzędzi znajdziesz w notatkach do tego odcinka. W zależności od narzędzia i języka, w którym pracujemy, różne są metody dokumentowania tych fragmentów kodu. Na przykład w Pythonie Używając sphinxa możemy dokumentację umieścić zaraz po nazwie funkcji, którą definiujemy, rozpoczynając to poprzez trzy cudzysłowy, jakiś kawałek tekstu i później dla każdego parametru wpisujemy jego nazwę, jego typ danych i możemy też podać przykład użycia tej funkcji.
Ewentualnie możemy również automatyczne generowanie dokumentacji zawrzeć jako jeden z etapów, jako jeden z kroków naszego workflow, pipeline, czy jakkolwiek nazywamy ten etap w naszym silniku CI-CD. Wspomniałem o tym, jak w Pythonie taką dokumentację zawrzeć. Mnie bliższa jest infrastruktura jako kod i to podejście. I w Teleformie najczęściej stosowanym jest Teleform Docs, by jego użyć. Musimy w pliku readme, którą chcemy tą dokumentację mieć automatycznie wygenerowaną, założyć tzw. hooki, czyli jakby taki początek i koniec fragmentu tego dokumentu, który będzie zastępowany automatycznie za każdym razem, kiedy uruchomimy narzędzie Terraform Docs.
Np. kiedy dodamy tego hooka również do pre-commit i za każdym razem będzie się ten Terraform Docs uruchamiał, gdy będziemy robić commit do naszego gita. Jak skonfigurować Terraform Docs w Precommit? Również znajdziesz link do mojego przykładu, jak ja to robię, do mojego repozytorium. Link znajdziesz w notatkach do tego odcinka. Jak widzisz, narzędzi jest wiele w zależności od języka, w którym pracujemy. Możliwości również możemy je, te narzędzia, uruchomić lokalnie, w pre-comicie, CI, CD, jako krok naszego workflow, pipeline'u i tak dalej. Możliwości mamy wiele. Ważne, by zacząć stosować te narzędzia i nie robić manualnie aktualizacji, dokumentacji na Confluence'ie czy innym narzędziu, tylko skorzystać z tego, co jest
I te kroki automatyzować. Unikniemy dzięki temu pomyłek. Nasza dokumentacja będzie zawsze aktualna. I zgodna z pewnymi strukturami, które są przyjęte w danym obszarze. Na przykład w wspomnianym Wam nie Terraformie. Terraform Docs generuje tą dokumentację w ten sposób, że mamy odpowiednie tabelki z parametrami wyjściowymi do danego modułu. Z parametrami wyjściowymi. Każdy trybut ma opisany typ danych, opis, przykład użycia. Te tabelki są takie same, mają taką samą strukturę. Niezależnie od tego dla jakiego modułu to ReformDocs wykonamy. Dzięki temu struktura tej dokumentacji jest spójna i taka sama.
I nie musimy się martwić tym, że jeśli dodamy kolejny atrybut w naszym module, na przykład dodatkowe dane wyjściowe, to Terraform Docs automatycznie tą dokumentację zaktualizuje. Mam nadzieję, że ten odcinek zachęcił Cię do tego podejścia, by tą dokumentację, przynajmniej w większości części, generować automatycznie wtedy, gdy aktualizujemy nasz kod źródłowy. Zajrzyj proszę do przykładów, które zawarłem. Oczywiście skupiłem się na teoroformie, ale mam nadzieję, że samo podejście w analogiczny sposób możesz wykorzystać w języku, w którym ty pracujesz na co dzień. To wszystko, co przygotowałem dzisiaj. Serdecznie Cię zapraszam do kolejnego mojego odcinka za trzy tygodnie. Do usłyszenia.
Pokazano wszystkie 5 dopasowań. Transkrypcja generowana automatycznie i niesprawdzana ręcznie — może zawierać błędy.
Kliknij, aby znaleźć fragmenty, w których pada.
Jak można ulepszyć lub uprościć tworzenie dokumentacji ? Jak zadbać o aktualność danych zawartych w dokumentacji ? Na te pytania odpowiem w odcinku, a materiały znajdziesz na https://github.com/sebastianczech/podcast-everything-as-a-code/tree/main/episode-016.