Z doświadczenia wiem, że nikt nie lubi czytać wstępów. Jednak zachęcam Cię do
przeczytania tych kilku krótkich sekcji. Dzięki temu, zrozumiesz co, komu i w
jaki sposób chciałem przekazać za pomocą tego przewodnika.
<h2>Dla kogo jest ten przewodnik?</h2>
Dla osób zajmujących się tworzeniem dokumentacji do oprogramowania. Twoje
stanowisko może mieć różne nazwy, ale ja dla uproszczenia będę się w tym
przewodniku posługiwał określeniem "Tech Writer".
<h2>Po co powstał ten przewodnik?</h2>
Moim celem nie jest zrobienie z Ciebie programisty. Nie dlatego, że nie jest to
możliwe, tylko dlatego, że jako Tech Writer wnosisz dużo do swojej organizacji.
Poza tym, bycie programistą to coś więcej niż tylko nauczenie się składni
jakiegoś języka. To zestaw umiejętności oraz odpowiedni sposób myślenia. Tak
samo jest w przypadku pisania dokumentacji. Umiejętność pisania w dicie czy
obsługi narzędzia typu HAT nie zrobi z Ciebie Tech Writera. Więc zostań tam
gdzie jesteś.
Moim celem jest zrobienie z Ciebie kodującego Tech Writera. Specjalnie używam
słowa "kodować" zamiast "programować", żeby jasno rozróżnić pomiędzy tym co robi
techniczny Tech Writer, a zawodowy programista. Nie staraj się zostać ekspertem
w danym języku programowania. Potraktuj kodowanie jako narzędzie, które ułatwi
Ci osiąganie celów dokumentacyjnych. Niech to będzie kolejna umiejętność, która
zrobi z Ciebie jeszcze lepszego Tech Writera.
Ten przewodnik ma za zadanie wprowadzić Cię w świat kodowania w Pythonie i
zachęcić Cię do pogłębiania wiedzy w tym obszarze. Dzięki temu łatwiej będzie Ci
tworzyć praktyczne rozwiązania, które usprawnią proces tworzenia dokumentacji i
pozwolą Ci lepiej zintegrować się z tym co robią programiści w Twojej
organizacji.
<h2>Dlaczego warto kodować?</h2>
Pewnie zastanawiasz się po co Ci kodowanie, skoro budowaniem aplikacji zajmuje
się ktoś inny, a Twoim zadaniem jest ich opisywanie. Nauka kodowania jest dla
Ciebie wartościowa z kilku powodów:
<ul>
<li>Będziesz w stanie lepiej zrozumieć o czym mówią programiści. To na pewno
ułatwi Ci pracę.</li>
<li>Ucząc się kodowania masz okazję korzystać z tych samych źródeł wiedzy co
programiści. Dzięki temu lepiej zrozumiesz jak pracują i z jakimi wyzwaniami
się mierzą. To z kolei pozwoli Ci na łatwiejsze budowanie relacji z nimi. Poza
tym łatwiej będzie Ci zagaić do nich przy kawie.</li>
<li>Będziesz w stanie tworzyć rozwiązania, takie jak skrypty, które zautomatyzują
nudną i powtarzalną część Twojej pracy. Na przykład, zamiast generować 10
wersji dokumentu poprzez klikanie i czekanie a potem przenoszenie ich w
miejsce docelowe, napiszesz skrypt, który uruchomi budowanie dokumentów, a
potem przekopiuje je gdzie trzeba. Przekazując takie zadania maszynie będziesz
mieć więcej czasu na zajęcie się tym co jest ważne w pracy Tech Writera, a
czego maszyna nie potrafi tak dobrze jak Ty, czyli tworzeniem użytecznej
treści.</li>
<li>Jest to dobre ćwiczenie mentalne. Zmusisz swój mózg do innego rodzaju
aktywności od tego co robisz na co dzień jako Tech Writer.</li>
<li>Zrozumiesz, że pisanie dokumentacji podczas kodowania nie jest do końca
naturalną rzeczą. Kiedy zatopisz się w kodowaniu, wchodzisz w tryb rozmowy z
maszyną i skupiasz się na rozwiązaniu problemu. Nie jest łatwo przełączyć się
na tryb rozmowy z człowiekiem, czyli pisanie dokumentacji. Dlatego następnym
razem kiedy programista nie doda dokumentacji do swojego kodu, spojrzysz na
niego łaskawszym okiem.</li>
</ul>
<h2>Dlaczego Python?</h2>
Python jest dobrym językiem, żeby rozpocząć przygodę z kodowaniem. Jego składnia
jest prosta i przejrzysta, dlatego pierwsze proste skrypty jesteś w stanie
zacząć pisać szybko. To trochę jak mówienie po angielsku do komputera.
Uszczypliwi twierdzą wręcz, że składnia Pythona przypomina bardziej pseudokod
niż prawdziwy kod. O ile dla programisty takie stwierdzenie może być obelgą i
spowodować, że ucierpi na tym jego ego, o tyle dla Tech Writera jest to jak
najbardziej pozytywna rzecz, bo łatwiej jest się nauczyć takiej składni.
Słyszałem kiedyś takie stwierdzenie, że łatwa składnia Pythona ułatwia skupienie
się na problemie, który chcemy rozwiązać zamiast na tym jak napisać kod.
Jednak, żeby wszystko było jasne - Python nie jest prymitywny. To język, który
ma wiele twarzy. Jeśli potrzebujesz prostego skryptu, to możesz go napisać w
relatywnie krótkim czasie nie rozumiejąc dogłębnie wszystkich aspektów tego
języka. Ale jeśli potrzebujesz napisać rozbudowaną aplikację, Python też to
potrafi.
Kiedyś przyszła mi do głowy taka analogia - Python dla Tech Writera jest jak
Markdown dla programisty. Nie zajmujesz się zawodowo programowaniem i kodowanie
jest dla Ciebie kolejnym narzędziem do osiągania dokumentacyjnych celów, dlatego
potrzebujesz czegoś łatwego i przyjemnego. Tak samo jest w przypadku
programistów. Ich głównym zadaniem jest programowanie, a nie pisanie
dokumentacji, dlatego również potrzebują czegoś z czego można szybko zacząć
korzystać.
<h2>Jak będziemy się uczyć?</h2>
Python jak by nie było jest językiem. Co prawda programowania, ale nadal
językiem. Każdy kto uczęszczał do szkoły miał okazję uczyć się (lub być uczonym)
jakiegoś języka. Dlatego chciałbym podejść do nauki Pythona jak do nauki języka
angielskiego. Jednak w przeciwieństwie do tradycyjnej szkoły, w tym przewodniku
"gramatyką" zajmiemy się tylko do takiego stopnia, żeby było wiadomo co się
dzieje i żeby mieć poczucie komfortu w trakcie pisania kodu. Nie zrozum mnie
źle, gramatyka jest ważna i jej znajomość jest jak najbardziej wartościowa, ale
na etapie gdzie zaczynasz swoją przygodę z językiem skupimy się na
"konwersacjach".
Wskoczymy na głęboką wodę i od razu zaczniemy rozmawiać z komputerem. Na
początku nie będziesz do końca rozumieć co mówisz, pewne zasady być może będą
dla Ciebie niejasne, ale będziesz mieć poczucie, że uczysz się czegoś
praktycznego i będziesz od razu widzieć efekty tej nauki. Czyli będzie dokładnie
tak jak podczas nauki angielskiego poprzez konwersacje z native speakerem.
Zamiast uczyć się reguł kodowania w Pythonie, żeby potem błyszczeć w
towarzystwie wiedzą teoretyczną, stworzymy razem przykładową aplikację, dzięki
której nauczysz się czegoś praktycznego i zobaczysz w jakich obszarach znajomość
Pythona może Ci pomóc w pracy Tech Writera. Zatem, nie przedłużając, przystąpmy
do kodowania.

Na początek trochę teorii

Być może z rozpędu czy też przyzwyczajenia przejście od razu do części
praktycznej tego przewodnika wydało Ci się dobrym pomysłem. Jeśli tak się stało,
to zachęcam Cię do przeczytania <a href="teoria.md">części teoretycznej</a>, żeby
dowiedzieć się jaki miałem cel pisząc ten przewodnik i jakie powinny być Twoje
oczekiwania w stosunku do tego co tu znajdziesz.
<h2>Co będziemy robić?</h2>
Jak to co? Kodować w Pythonie! 🙂
W świecie dokumentacji do oprogramowania, istnieje wiele miejsc, gdzie
tradycyjne "kopiuj-wklej" można potencjalnie zastąpić jakimś automatycznym
rozwiązaniem, które odwali za nas brudną robotę.
Wyobraź sobie taki scenariusz. Dostajesz przydział do projektu, w którym
będziesz bardzo blisko współpracować z programistami. Ustaliliście na samym
początku, że za każdym razem kiedy programista zrobi zmianę w kodzie, która musi
zostać udokumentowana, doda do folderu <code>docs</code> plik tekstowy z opisem zmian. Plik
będzie miał taką nazwę jak numer historyjki w systemie do śledzenia zadań. Na
przykład, jeśli historyjka ma numer PROJ-102 i została stworzona po to, żeby
programista naprawił błąd powodujący, że aplikacja zawieszała się na kilka
sekund, a następnie okno aplikacji przesuwało się poza ekran, to programista w
repozytorium z kodem doda plik <code>docs\PROJ-102.txt</code>, w którym będzie taka
informacja.
PROJ-102.txt
<blockquote>
Naprawiliśmy błąd, który powodował, że aplikacja zawieszała się na kilka
sekund, a następnie okno aplikacji przesuwało się poza ekran przez co stawało
się niewidoczne.
</blockquote>
Co kilka tygodni zespół publikuje nową wersję aplikacji wraz z aktualną
dokumentacją, której częścią są release notes (noty wydania). Treść, która
trafia do release notes pochodzi z plików tekstowych, które dodają programiści
kiedy zmieniają kod. Twoim zadaniem, jako Tech Writera, jest sprawdzanie
informacji w tych plikach, poprawianie ich, a na końcu wygenerowanie pliku HTML
z gotowymi notami. Jest to prosty plik z tabelką przedstawiającą zmiany w
aplikacji. Chodzi o coś takiego.
<table>
<thead>
<tr>
<th>Numer zgłoszenia</th>
<th>Opis</th>
</tr>
</thead>
<tbody>
<tr>
<td>PROJ-102</td>
<td>Naprawiliśmy błąd, który powodował, że aplikacja zawieszała się na kilka sekund, a następnie okno aplikacji przesuwało się poza ekran przez co stawało się niewidoczne.</td>
</tr>
<tr>
<td>PROJ-101</td>
<td>Dodaliśmy nową funkcję, która pozwala na szybkie pobieranie zasobów sieciowych.</td>
</tr>
</tbody>
</table>
Nie chcesz generować pliku HTML poprzez ręczne przeklejanie informacji z plików
tekstowych i potem wprowadzanie pozostałych poprawek, dlatego szukasz bardziej
sprytnego rozwiązania. Chcesz swój czas i energię przeznaczyć głównie na
ulepszanie informacji, które dostarczają Ci programiści, a proces publikowania
końcowego pliku chcesz przekazać maszynie.
I to właśnie będzie nasz cel, który będziemy krok po kroku realizować w
kolejnych sekcjach. Zbudujemy razem przykładowy generator treści, który pobiera
informacje z plików tekstowych, a następnie generuje docelowy plik HTML na
podstawie szablonu.

Przechodzimy do praktyki

<h2>Co nam będzie potrzebne?</h2>
Starałem się ograniczyć liczbę potrzebnych komponentów do minimum, żebyśmy mogli
przejść jak najszybciej do kodowania. Jednak pewnych rzeczy nie da się pominąć,
dlatego będziesz potrzebować takiego oprogramowania.
<h3>Python</h3>
Pythona trzeba zainstalować. W niektórych systemach operacyjnych, może już być
zainstalowany, ale istnieje spora szansa, że nie będzie to wersja, której
potrzebujemy. A będziemy potrzebować wersji 3.7 lub nowszej.
Instalatory znajdziesz na oficjalnej stronie Pythona (<a href="https://www.python.org/">https://www.python.org/</a>).
Możesz też zainstalować Pythona poprzez menedżera paczek w swoim systemie
operacyjnym. Kolejną opcją jest użycie narzędzia pyenv
(<a href="https://github.com/pyenv/pyenv">https://github.com/pyenv/pyenv</a>). W przypadku Windowsa możesz także skorzystać z
instalacji poprzez Microsoft Store.
Wybierz dogodną dla siebie metodę instalacji. Jeśli napotkasz jakieś problemy to
najlepiej poproś o pomoc kogoś kto ma doświadczenie z Pythonem albo poszukaj
informacji w internecie. Biorąc pod uwagę liczbę systemów operacyjnych,
potencjalna liczba problemów z instalacją jest spora, dlatego nie byłbym w
stanie pokryć w tym przewodniku każdej możliwej ścieżki.
Bez względu na to jaką wybierzesz metodę instalacji, zwróć uwagę, żeby dodać
Pythona do zmiennych środowiskowych, czyli przypisać komendę <code>python</code> do Pythona
3, którego zainstalujesz. Robi się to różnie w zależności od systemu
operacyjnego i sposobu instalacji. Na przykład, jeśli instalujesz Pythona na
Windowsie za pomocą instalatora pobranego z oficjalnej strony Pythona, na jednym
z ekranów będziesz mieć opcję, żeby dodać Pythona do zmiennych środowiskowych
(<code>PATH</code>).
<h3>Edytor tekstowy</h3>
Możesz użyć jakiegokolwiek edytora tekstowego, żeby kodować w Pythonie. Jednak
zachęcam Cię do skorzystania z edytora, który wspiera Pythona. Ułatwi Ci to
znacznie życie, bo taki edytor podpowie Ci podczas pisania jakie masz opcje,
automatycznie sformatuje Twój kod i da Ci znać jeśli coś będzie nie tak. Na
szczęście nie ma problemu ze znalezieniem odpowiedniego edytora, który jest
darmowy. Nie chcę Ci narzucać niczego, ale w momencie pisania tego przewodnika
popularnym i darmowym edytorem, który oferuje wsparcie dla Pythona jest Visual
Studio Code od Microsoftu (<a href="https://code.visualstudio.com/">https://code.visualstudio.com/</a>). Może ta opcja będzie
dla Ciebie odpowiednia.
Oprócz edytorów, możesz skorzystać z bardziej zaawansowanej opcji, czyli IDE
(ang. integrated development environment). Przykładem może być PyCharm od
JetBrains (<a href="https://www.jetbrains.com/pycharm/">https://www.jetbrains.com/pycharm/</a>). Jednak na nasze potrzeby jest to
za dużo. Nauczenie się obsługi IDE przyniesie Ci korzyści, ale na późniejszym
etapie nauki Pythona. Na tym etapie, polecam edytor tekstowy.
<h2>Kodowanie czas zacząć</h2>
Mam nadzieję, że instalacja Pythona i edytora nie przysporzyły Ci problemów i że
Twój zapał jest taki sam albo większy jak w momencie rozpoczęcia czytania tego
przewodnika. Skoro mamy już wszystko gotowe to zabieramy się do pracy.
Będziemy krok po kroku budować naszą aplikację. Pomimo tego, że ten przewodnik
jest napisany w języku polskim i nasze pliki tekstowe zawierają w sobie polski
tekst, to nasz kod będziemy pisać po angielsku. Być może wyda Ci się to dziwne,
ale według mnie jest to bardziej naturalne i powszechne. Poza tym, dzięki temu,
Twój kod będzie mógł bywać w świecie, bo Twoi anglojęzyczni znajomi też będą w
stanie go zrozumieć.
Jeśli chcesz od razu skoczyć na głęboką wodę albo po prostu jesteś ciekaw co tu
się wydarzy, przejdź do sekcji <a href="gotowa-aplikacja">Gotowa aplikacja</a>.

Przygotowanie

W dogodnej lokalizacji na swoim dysku, stwórz folder <code>rel_notes_generator</code>. W
tym folderze będziemy dodawać kolejne zasoby potrzebne nam do zbudowania
generatora.

Krok 1: Stwórz folder dla generatora

Stwórz folder <code>rel_notes_generator\input</code>, a w nim dodaj dwa pliki tekstowe,
<code>PROJ-101.txt</code> i <code>PROJ-102.txt</code>, z taką zawartością jak widać poniżej. Tymi
plikami "nakarmimy" nasz generator. Dzięki temu będziemy mogli sprawdzić czy
działa tak jak tego chcemy.
PROJ-101.txt
<blockquote>
Dodaliśmy nową funkcję, która pozwala na szybkie pobieranie zasobów
sieciowych.
</blockquote>
PROJ-102.txt
<blockquote>
Naprawiliśmy błąd, który powodował, że aplikacja zawieszała się na kilka
sekund, a następnie okno aplikacji przesuwało się poza ekran przez co stawało
się niewidoczne.
</blockquote>

Krok 2: Dodaj przykładowe pliki tekstowe

Mamy już pliki tekstowe, z których pobierzemy treść naszych not wydania. Teraz
potrzebujemy jeszcze szablonu, do którego wstawimy informacje pobrane z plików
tekstowych. Stwórz plik <code>rel_notes_generator\release_notes_template.html</code> z
takim kodem HTML.
release_notes_template.html
<pre><code class="language-html">&#x3C;!DOCTYPE html>
&#x3C;html lang="en">
 &#x3C;head>
 &#x3C;meta charset="utf-8" />
 &#x3C;title>Noty wydania&#x3C;/title>
 &#x3C;/head>

 &#x3C;body>
 &#x3C;table>
 &#x3C;tr>
 &#x3C;th>Numer zgłoszenia&#x3C;/th>
 &#x3C;th>Opis&#x3C;/th>
 &#x3C;/tr>
 $release_notes
 &#x3C;/table>
 &#x3C;/body>
&#x3C;/html>
</code></pre>
Ten prosty plik zawiera tabelkę, która póki co ma tylko jeden wiersz z dwoma
kolumnami (<code>Numer zgłoszenia</code> i <code>Opis</code>) oraz tajemniczy element
<code>$release_notes</code>. Jest to element zastępczy, który zostanie zamieniony przez
nasz generator na informacje pobrane z plików tekstowych. W kroku 5 poznasz
komponent Pythona, który będzie w stanie zrobić użytek z tego elementu.

Krok 3: Stwórz szablon dla pliku HTML

Stwórz plik <code>rel_notes_generator\rel_notes_generator.py</code>. Pliki zawierające kod
Pythona mają rozszerzenie <code>.py</code>. W tym pliku będzie znajdował się kod dla
naszego generatora, który napiszemy w kolejnych krokach.

Krok 4: Stwórz plik dla kodu generatora

Python zawiera w sobie bogaty zestaw gotowych komponentów, z których możemy
korzystać od razu bez instalowania dodatkowego oprogramowania. Ten zestaw nazywa
się The Python Standard Library. Żeby móc skorzystać z jakiegoś komponentu
musimy go zaimportować w naszej aplikacji, czyli tak jakby dodać do niego link.
Możemy to zrobić wpisując:
<pre><code class="language-python">import nazwaKomponentu
</code></pre>
albo
<pre><code class="language-python">from nazwaKomponentu import nazwaElementu
</code></pre>
Różnica jest taka, że w pierwszym sposobie importujemy cały komponent a w drugim
tylko określone elementy, których akurat potrzebujemy.
Nasz generator będzie korzystał z trzech elementów, które są w trzech różnych
komponentach. Dlatego na początku naszego kodu w pliku <code>rel_notes_generator.py</code>
musimy dodać takie linijki.
rel_notes_generator.py
<pre><code class="language-python">from string import Template
from pathlib import Path
from shutil import rmtree
</code></pre>
Z komponentu <code>string</code> importujemy element <code>Template</code>, który pozwala na obsługę
szablonów. Będzie on nam potrzebny, żeby odpowiednio opakować informacje pobrane
z plików tekstowych i potem je podstawić w odpowiednie miejsce w szablonie HTML.
Jak pamiętasz, w kroku 3 pojawił się element zastępczy <code>$release_notes</code>.
Dodaliśmy go do naszego szablonu po to, żeby komponent <code>Template</code> wiedział gdzie
ma wstawić właściwe informacje.
Z komponentu <code>pathlib</code> importujemy element <code>Path</code>, dzięki któremu w elegancki
sposób będziemy mogli ustawić w naszej aplikacji ścieżki do potrzebnych zasobów.
Z komponentu <code>shutil</code> importujemy element <code>rmtree</code>, który pozwala na usuwanie
folderów, nawet jeśli nie są puste.

Krok 5: Dodaj linki do potrzebnych komponentów Pythona

W naszym generatorze musimy ustawić trzy ścieżki w taki oto sposób.
rel_notes_generator.py
<pre><code class="language-python">current_dir = Path(__file__).parent
input_dir = current_dir / 'input'
output_dir = current_dir / 'output'
</code></pre>
Zanim przejdę do wyjaśnienia o co dokładnie tutaj chodzi, wspomnę tylko, że
zmienne w Pythonie tworzymy poprzez przypisanie jakiejś wartości do nazwy. Na
przykład, jeśli chciałbym stworzyć zmienną <code>name</code>, która będzie przechowywać w
sobie moje imię i nazwisko, to muszę zrobić to tak.
<pre><code class="language-python">name = 'Michał Skowron'
</code></pre>
W Pythonie możesz używać zarówno pojedynczych (<code>''</code>) jak i podwójnych (<code>""</code>)
cudzysłowów.
Ale wróćmy do naszych ścieżek. Na początku, ustawiamy <code>current_dir</code> czyli
ścieżkę do folderu, w którym znajduje się nasz plik <code>rel_notes_generator.py</code>.
Robimy to za pomocą elementu <code>__file__</code> dostępnego w Pythonie. Ten element
przechowuje ścieżkę do pliku. Dodając <code>.parent</code> mówimy Pythonowi, że chcemy w
naszej zmiennej zapisać nie ścieżkę do naszego pliku, tylko do folderu, w którym
nasz plik się znajduje.
Pewnie zastanawiasz się po co jest nam to potrzebne? Jest to ogólnie dobra
praktyka. Korzystając z niej ułatwiamy sobie życie, bo nie musimy na sztywno
wpisywać ścieżki do naszego pliku. Dzięki temu nie ma znaczenia gdzie znajduje
się nasz plik <code>rel_notes_generator.py</code>, bo Python sam sobie rozwiąże tę ścieżkę.
Ta ścieżka jest naszym punktem wyjścia dla kolejnych ścieżek. Na jej podstawie
budujemy ścieżkę do folderu <code>input</code>, w którym trzymamy pliki tekstowe i do
folderu <code>output</code>, w którym zapisujemy nasz końcowy plik HTML.
Możliwe, że zastanawiasz się teraz czy nie dałoby się tego zrobić prościej i
uniknąć tej szamanerii. Dałoby się, ale niekoniecznie byłoby to lepsze
rozwiązanie. Gdybyśmy nie skorzystali z elementu <code>__file__</code>, musielibyśmy
ustawić ścieżki "na piechotę". Wyobraź sobie, że Twój plik
<code>rel_notes_generator.py</code> znajduje się w <code>C:\my-apps\rel_notes_generator</code>. Więc
ustawiasz ścieżki na sztywno w taki sposób.
<pre><code class="language-python">current_dir = 'C:\my-apps\rel_notes_generator'
input_dir = current_dir + '\' + 'input'
output_dir = current_dir + '\' + 'output'
</code></pre>
Takie rozwiązanie na pierwszy rzut oka może Ci się wydawać całkiem w porządku,
ale niestety niesie ze sobą parę problemów. Generator będzie działał tylko wtedy
jeśli:
<ul>
<li>Uruchomimy go na Windowsie</li>
<li>Nasz folder projektu będzie nazywał się <code>rel_notes_generator</code> i będzie
znajdował się w <code>C:\my-apps</code>.</li>
</ul>
Jeśli zmienimy nazwę folderu projektu albo przeniesiemy go w inne miejsce, to
nasz generator przestanie działać. To dość spore ograniczenia, których możemy
uniknąć stosując komponent <code>pathlib</code> i ścieżkę do folderu projektu, która sama
się automatycznie rozwiązuje.

Krok 6: Ustaw ścieżki do potrzebnych zasobów

Teraz dodamy naszą pierwszą funkcję.
Funkcja w kodzie to nic innego jak kawałek kodu, który wykonuje jakąś operację.
Będzie nam ona potrzebna, żeby z naszych plików tekstowych pobrać ich nazwę i
zawartość.
Dodaj do pliku <code>rel_notes_generator.py</code> następujący kod.
rel_notes_generator.py
<pre><code class="language-python">def get_release_notes(source_dir):
 rel_notes = {}
 for file in source_dir.glob('*.txt'):
 rel_note_id = file.stem
 with file.open() as f:
 rel_note_text = f.read()
 rel_notes[rel_note_id] = rel_note_text
 return rel_notes
</code></pre>
W Pythonie, tworzymy funkcję za pomocą słowa <code>def</code>. Następnie podajemy nazwę
funkcji i opcjonalnie w nawiasie określamy parametry, które funkcja przyjmuje.
W naszym wypadku funkcja nazywa się <code>get_release_notes</code>. Żeby mogła wykonać
poprawnie swoje zadanie, musimy podać jej ścieżkę do folderu, w którym znajdują
się pliki tekstowe (<code>source_dir</code>).
Pierwsze koty za płoty. Idziemy dalej. Nasza funkcja ma za zadanie przejść przez
wszystkie pliki i zebrać z nich nazwę i zawartość. Zgodnie z tym co zostało
ustalone z programistami w Twoim projekcie, nazwa pliku to numer zgłoszenia, a
zawartość to opis wprowadzonych zmian w kodzie aplikacji. W związku z tym,
wygodnie będzie nam zapisać informacje zebrane przez naszą funkcję w formie
słownika (<code>dict</code>), czyli takiego zbioru elementów <code>klucz: wartość</code>. W Pythonie,
słownik to jeden z najważniejszych typów danych, który jest bardzo często
używany.
W naszym wypadku, taka para będzie wyglądać tak: <code>numer zgłoszenia: opis zmian</code>.
Na początku dodajemy zmienną <code>rel_notes</code>, która będzie przechowywać pusty
słownik (<code>{}</code>). Potem ten pusty słownik wypełnimy danymi, które nasza funkcja
zbierze.
W folderze może znajdować się więcej niż jeden plik tekstowy, więc musimy zrobić
pętlę, która przejdzie po wszystkich plikach. Innymi słowy, mówimy Pythonowi,
żeby dla każdego pliku (<code>for file</code>), który ma rozszerzenie TXT
(<code>in source_dir.glob('*.txt')</code>):
<ol>
<li>W zmiennej <code>rel_note_id</code> zapisał nazwę pliku (<code>file.stem</code>).</li>
<li>Otworzył plik (<code>with file.open() as f</code>) i w zmiennej <code>rel_note_text</code> zapisał
jego zawartość, którą pobrał (<code>f.read()</code>).</li>
<li>Do słownika dodał parę z numerem zgłoszenia i opisem zmian
(<code>rel_notes[rel_note_id] = rel_note_text</code>).</li>
</ol>
Kiedy pętla przejdzie po wszystkich plikach, funkcja zwróci nam wypełniony
słownik (<code>return rel_notes</code>). W naszym testowym środowisku, funkcja zwróci nam
taki słownik:
<pre><code class="language-json">{
 "PROJ-101": "Dodaliśmy nową funkcję, która pozwala na szybkie pobieranie zasobów sieciowych.",
 "PROJ-102": "Naprawiliśmy błąd, który powodował, że aplikacja zawieszała się na kilka sekund, a następnie okno aplikacji przesuwało się poza ekran przez co stawało się niewidoczne."
}
</code></pre>
Na tym etapie, tylko stworzyliśmy nową funkcję, ale jeszcze jej nie
uruchomiliśmy. To zrobimy dopiero później.

Krok 7: Dodaj funkcję do wyciągania informacji z plików źródłowych

W poprzednim kroku zrobiliśmy całkiem sporo, ale to dopiero początek. Potrzebne
nam będą jeszcze inne funkcje, żeby nasza aplikacja zrobiła wszystko co to
chcemy, czyli stworzyła dla nas plik HTML z notami wydania.
W tym kroku dodamy funkcję i prosty szablon, który pozwoli nam przerobić słownik
na fragment kodu HTML. Będą to wiersze tabeli, które podstawimy w kolejnych
krokach do naszego szablonu HTML. Jak pamiętasz, szablon przygotowaliśmy w
kroku 3.
Na początek, dodaj taki mały szablon.
rel_notes_generator.py
<pre><code class="language-python">rel_note_template = Template('''&#x3C;tr>
&#x3C;td>$id&#x3C;/td>
&#x3C;td>$description&#x3C;/td>
&#x3C;/tr>
''')
</code></pre>
Szablon ma w sobie dwa elementy zastępcze, <code>$id</code> i <code>$description</code>, które
będziemy zamieniać odpowiednio na klucz i wartość ze słownika. Potrójny
cudzysłów (<code>'''</code> lub <code>"""</code>) służy do tworzenia łańcuchów znaków, które zajmują
więcej niż jedną linijkę. Dla łańcuchów znaków, które nie wykraczają poza jedną
linijkę używa się pojedynczego cudzysłowu (<code>'</code> lub <code>"</code>).
Następnie dodaj kolejną funkcję.
rel_notes_generator.py
<pre><code class="language-python">def generate_release_notes(release_notes):
 rel_note_table_rows = ''
 for id, description in release_notes.items():
 rel_note_table_rows += rel_note_template.substitute(
 id=id, description=description)
 return rel_note_table_rows
</code></pre>
Jej zadaniem będzie przekształcenie słownika we fragment kodu HTML. W poprzednim
kroku analizowaliśmy poszczególne części składowe funkcji, więc pewnie ta
funkcja nie jest już dla Ciebie wielką niewiadomą. Jednak dla porządku przejdźmy
po tym co się tutaj dzieje.
Nasza funkcja o nazwie <code>generate_release_notes</code> przyjmuje jako parametr słownik
(<code>release_notes</code>), w którym są pary <code>numer zgłoszenia: opis zmian</code>.
Na początku, tworzymy zmienną <code>rel_note_table_rows</code>, której wartość to pusty
tekst (<code>''</code>). W tej zmiennej zapiszemy nasze wiersze tabeli HTML, które
wygenerujemy za pomocą naszego szablonu <code>rel_note_template</code>.
Następnie, mówimy Pythonowi, żeby dla każdej pary (<code>for id, description</code>) w
słowniku (<code>release_notes.items()</code>):
<ol>
<li>Wziął szablon <code>rel_note_template</code> i podmienił w nim element zastępczy <code>$id</code>
na <code>id</code> ze słownika (czyli numer zgłoszenia) i zamienił element zastępczy
<code>$description</code> na <code>description</code> ze słownika. Innymi słowy pobieramy ze
słownika numer zgłoszenia i opis zmian i wstawiamy je do szablonu
(<code>rel_note_template.substitute(id=id, description=description)</code>).</li>
<li>Dodał wygenerowany wiersz tabeli HTML do zmiennej, którą stworzyliśmy na
początku (<code>rel_note_table_rows +=</code>).</li>
</ol>
Kiedy pętla przejdzie po wszystkich parach w słowniku, funkcja zwróci nam
zmienną z gotowymi wierszami tabeli (<code>return rel_note_table_rows</code>). W naszym
testowym środowisku, funkcja zwróci nam taki kod:
<pre><code class="language-html">&#x3C;tr>
 &#x3C;td>PROJ-101&#x3C;/td>
 &#x3C;td>
 Dodaliśmy nową funkcję, która pozwala na szybkie pobieranie zasobów
 sieciowych.
 &#x3C;/td>
&#x3C;/tr>
&#x3C;tr>
 &#x3C;td>PROJ-102&#x3C;/td>
 &#x3C;td>
 Naprawiliśmy błąd, który powodował, że aplikacja zawieszała się na kilka
 sekund, a następnie okno aplikacji przesuwało się poza ekran przez co
 stawało się niewidoczne.
 &#x3C;/td>
&#x3C;/tr>
</code></pre>
Dla przypomnienia dodam, że tak jak w poprzednim kroku, tylko stworzyliśmy nową
funkcję, ale jeszcze jej nie uruchomiliśmy. To zrobimy dopiero później.

Krok 8: Dodaj funkcję generującą wiersze tabeli

To już ostatnia funkcja, której potrzebujemy. Jej zadaniem jest podstawienie
wierszy tabeli do szablonu pliku HTML, a następnie zapisanie końcowego pliku
HTML z notkami wydania. Dodaj taki kod do pliku <code>rel_notes_generator.py</code>.
rel_notes_generator.py
<pre><code class="language-python">def write_release_notes(release_note_rows, target_dir):
 if target_dir.exists():
 rmtree(target_dir)
 target_dir.mkdir()
 with Path('release_notes_template.html').open() as rnt:
 file_template = Template(rnt.read())
 with (target_dir / 'release_notes.html').open('w') as rn:
 rn.write(file_template.substitute(release_notes=release_note_rows))
</code></pre>
Na początku funkcja sprawdza czy folder docelowy, w którym zapiszemy końcowy
plik już istnieje (<code>target_dir.exists()</code>). Jeśli tak, to najpierw go kasuje
(<code>rmtree(target_dir)</code>). Następnie, funkcja tworzy folder docelowy
(<code>target_dir.mkdir()</code>). Te wszystkie kroki możemy wykonać w łatwy sposób dzięki
komponentom <code>pathlib</code> i <code>shutil</code>, które zaimportowaliśmy w kroku 5.
Po przygotowaniu folderu docelowego, funkcja otwiera plik szablonu HTML
(<code>with Path('release_notes_template.html').open() as rnt</code>) po czym przypisuje
zawartość szablonu do zmiennej <code>file_template</code>
(<code>file_template = Template(rnt.read())</code>).
Następnie, funkcja tworzy pusty plik końcowy o nazwie <code>release_notes.html</code>
(<code>with (target_dir / 'release_notes.html').open('w') as rn</code>). Ostatnia część to
zamiana w szablonie HTML elementu zastępczego <code>$release_notes</code> na właściwe
wiersze tabeli i zapisanie tego kodu HTML do pliku końcowego
(<code>rn.write(file_template.substitute(release_notes=release_note_rows))</code>).
Funkcja jest dość krótka, ale całkiem sporo się tutaj wydarzyło. To jest właśnie
jedna z zalet Pythona - zwięzła i czytelna składnia, dzięki której można na
niewielkiej przestrzeni zawrzeć całkiem sporo logiki.
Tak jak poprzednio, na razie tylko zdefiniowaliśmy funkcję. Teraz musimy ją
jeszcze uruchomić.

Krok 9: Dodaj funkcję zapisującą końcowy plik HTML

To już ostatnia prosta. Właściwie mamy już wszystko co nam potrzebne. Teraz
pozostaje nam uruchomić nasze funkcje.
Żeby to zrobić, dodaj taki kod.
rel_notes_generator.py
<pre><code class="language-python">if __name__ == '__main__':
 collected_release_notes = get_release_notes(input_dir)
 generated_table_rows = generate_release_notes(collected_release_notes)
 write_release_notes(generated_table_rows, output_dir)
</code></pre>
Pierwsza linijka, <code>if __name__ == '__main__'</code>, wygląda dość enigmatycznie. W
Pythonie w taki sposób określamy, że dany fragment kodu ma zostać uruchomiony
tylko jeśli wywołamy plik <code>.py</code> jako skrypt z linii komend. Dzięki temu, ten
fragment kodu nie zostanie wywołany jeśli zaimportujemy nasz plik <code>.py</code> do
innego pliku. Zapewne to wszystko brzmi dość zagadkowo, dlatego postaram się to
rozjaśnić na przykładzie.
Kod naszego generatora znajduje się w pliku <code>rel_notes_generator.py</code>. W
większości przypadków będziesz uruchamiać generator z linii komend jak skrypt za
pomocą polecenia <code>python rel_notes_generator.py</code>. Kiedy to zrobisz, część kodu,
która znajduje się pod <code>if __name__ == '__main__'</code> zostanie wykonana. Czyli
wszystko się zgadza, to jest właśnie to o co nam chodzi.
Po pewnym czasie, stworzysz kolejny generator, który będzie miał trochę inne
funkcje niż generator, który stworzyliśmy wspólnie. Jednak pewne części będą
takie same. Żeby nie pisać tego samego kodu jeszcze raz, możesz zaimportować
<code>rel_notes_generator.py</code> do swojego nowego generatora w taki sam sposób jak
importowaliśmy komponenty w kroku 5. W tej sytuacji chcesz tylko zaimportować
funkcje z generatora, ale nie chcesz, żeby się uruchomiły. O tym kiedy je
uruchomić, zdecydujesz w odpowiedniej części swojego nowego generatora. I
właśnie użycie <code>if __name__ == '__main__'</code>, powoduje że funkcje się nie
uruchomią. Podczas importu funkcji, wszystko co znajduje się poniżej tej linijki
nie wykona się.
Skoro już wiemy po co nam ten enigmatyczny fragment kodu, zobaczmy co znajduje
się pod nim. Najpierw, uruchamiamy funkcję <code>get_release_notes</code> na folderze
<code>input</code>, czyli tam gdzie mamy nasze testowe pliki tekstowe. Dla przypomnienia,
funkcja wyciągnie nam nazwy i zawartość plików tekstowych. Wynik uruchomienia
funkcji przypisujemy do zmiennej <code>collected_release_notes</code>. Następnie,
uruchamiamy funkcję <code>generate_release_notes</code>, która stworzy nam wiersze tabeli
HTML z zawartości plików tekstowych, którą trzymamy w zmiennej
<code>collected_release_notes</code>. Wygenerowane wiersze tabeli przypisujemy do zmiennej
<code>generated_release_notes</code>. Ostatnia operacja, to uruchomienie funkcji
<code>write_release_notes</code>, która zapisze to co mamy w zmiennej
<code>generated_release_notes</code> do końcowego pliku HTML.
Nasze noty wydania są gotowe!

Krok 10: Ostatnie szlify

Udało się nam przejść przez wszystkie etapy tworzenia generatora. Poniżej
kompletny kod naszej aplikacji.
rel_notes_generator.py
<pre><code class="language-python">from string import Template
from pathlib import Path
from shutil import rmtree

current_dir = Path(__file__).parent
input_dir = current_dir / 'input'
output_dir = current_dir / 'output'

rel_note_template = Template('''&#x3C;tr>
&#x3C;td>$id&#x3C;/td>
&#x3C;td>$description&#x3C;/td>
&#x3C;/tr>
''')


def get_release_notes(source_dir):
 rel_notes = {}
 for file in source_dir.glob('*.txt'):
 rel_note_id = file.stem
 with file.open() as f:
 rel_note_text = f.read()
 rel_notes[rel_note_id] = rel_note_text
 return rel_notes


def generate_release_notes(release_notes):
 rel_note_table_rows = ''
 for id, description in release_notes.items():
 rel_note_table_rows += rel_note_template.substitute(
 id=id, description=description)
 return rel_note_table_rows


def write_release_notes(release_note_rows, target_dir):
 if target_dir.exists():
 rmtree(target_dir)
 target_dir.mkdir()
 with Path('release_notes_template.html').open() as rnt:
 file_template = Template(rnt.read())
 with (target_dir / 'release_notes.html').open('w') as rn:
 rn.write(file_template.substitute(release_notes=release_note_rows))

if __name__ == '__main__':
 collected_release_notes = get_release_notes(input_dir)
 generated_table_rows = generate_release_notes(collected_release_notes)
 write_release_notes(generated_table_rows, output_dir)
</code></pre>

Gotowa aplikacja

W kroku 10, pojawiła się już informacja jak wywołać plik <code>.py</code> z linii komend.
Jednak dla porządku, zamieszczam informację jak uruchomić generator:
<ol>
<li>
Otwórz linię komend.
</li>
<li>
Przejdź do folderu <code>rel_notes_generator</code>.
</li>
<li>
Uruchom poniższą komendę.
<pre><code class="language-bash">python rel_notes_generator.py
</code></pre>
W folderze <code>output</code> pojawi się plik <code>release_notes.html</code> z gotowymi notami
wydania.
</li>
</ol>
<blockquote>
W zależności od tego w jaki sposób Python został zainstalowany na Twoim
komputerze, komenda może się różnić. Na przykład, jeśli Python 3 nie został
dodany do zmiennych środowiskowych Twojego systemu operacyjnego, może
uruchomić się Python 2, który już wcześniej był zainstalowany na Twoim
komputerze. W innym wypadku, komenda może w ogóle nie zostać rozpoznana.
Możesz wtedy spróbować użyć komendy <code>python3</code>.
</blockquote>

Jak uruchomić generator?

Dotarliśmy do końca przewodnika. Dobra robota! Twoja pierwsza aplikacja w
Pythonie jest gotowa. Mam nadzieję, że to dopiero początek Twojej przygody z tym
językiem programowania i że udało mi się przekonać Cię, że warto przyjrzeć się
mu bliżej.
Jeśli chcesz dowiedzieć się więcej o Pythonie i komponentach dostępnych w The
Python Standard Library to polecam oficjalną dokumentację
(<a href="https://docs.python.org/3/">https://docs.python.org/3/</a>).
Możesz też dalej pracować nad generatorem, żeby stał się jeszcze lepszy. Oto
moje propozycje.
<h2>Wsparcie dla Markdowna</h2>
Źródłem dla generatora są zwykłe pliki tekstowe. To niesie ze sobą pewne
ograniczenia. Na przykład, nie możemy dodawać formatowania takiego jak
pogrubienie czy kursywa. Jeśli potrzebujesz używać Markdowna w plikach
tekstowych, możesz przyjrzeć się zewnętrznemu komponentowi Python Markdown
(<a href="https://python-markdown.github.io/">https://python-markdown.github.io/</a>). Nie jest on częścią The Python Standard
Library, więc trzeba go zainstalować za pomocą narzędzia <code>pip</code>.
<h2>Bardziej zaawansowane szablony</h2>
Możesz zastąpić element <code>Template</code> z komponentu <code>string</code> bardziej zaawansowanym
narzędziem do tworzenia szablonów. Jedną z możliwości jest jinja2
(<a href="https://jinja.palletsprojects.com/">https://jinja.palletsprojects.com/</a>), która oferuje naprawdę sporo możliwości.
<h2>Lepszy wygląd pliku HTML</h2>
Warto pomyśleć nad dodaniem jakichś ładnych stylów do pliku HTML. Do tego
będziesz potrzebować znajomości CSS. Możesz przyjrzeć się bibliotece
Bootstrap (<a href="https://getbootstrap.com/">https://getbootstrap.com/</a>) rozwijanej przez Twittera. Jest ona
bardzo popularna i pozwala niskim kosztem tworzyć atrakcyjne strony HTML.
To już wiedza wykraczająca poza Pythona, ale na pewno przyda Ci się ona
niejednokrotnie w przyszłości podczas tworzenia innych narzędzi.

Co dalej?

<h2>Paweł Kowaluk</h2>
Senior Technical Writer w Guidewire Software, mój dobry kolega i wieloletni
współpracownik. Na co dzień razem pracujemy, a w wolnym czasie nagrywamy podcast
"Tech Writer koduje".
Dziękuję za recenzję, wsparcie i pomoc w przygotowaniu oprawy graficznej.
Z Pawłem możecie się skontaktować za pomocą jego profilu na LinkedIn
(<a href="https://www.linkedin.com/in/pawel-kowaluk/">https://www.linkedin.com/in/pawel-kowaluk/</a>).
<h2>Sebastian Witowski</h2>
Konsultant i trener Pythona, mój znajomy z konferencji EuroPython 2019.
Dziękuję za recenzję merytoryczną.
W <a href="/blog/2020/03/24/14">14. odcinku podcasta "Tech Writer koduje"</a>,
rozmawialiśmy z Sebastianem o tym jak ustawić sobie środowisko do kodowania w
Pythonie i jakich błędów unikać zaczynając swoją przygodę z tym językiem
programowania. Polecam też warsztat "Modern Python Developer's
Toolkit"(<a href="https://www.youtube.com/watch?v=WkUBx3g2QfQ&#x26;feature=youtu.be">https://www.youtube.com/watch?v=WkUBx3g2QfQ&#x26;feature=youtu.be</a>), który
Sebastian przygotował w ramach konferencji PyCon US 2020.
Z Sebastianem możecie się skontaktować za pomocą jego strony
(<a href="https://switowski.com/">https://switowski.com/</a>).

Podziękowania

Paweł Kowaluk

Sebastian Witowski