Development Procedures (czech) ============================== Tento dokument popisuje postupy používané pri vývoji aplikace Adresářová struktura -------------------- * ``doc`` - Dokumentace * ``resources`` - Zdroje, které nejsou součástí aplikace * ``src/JobsScheduler`` - Modul pro vzdálené spouštění výpočtů * ``src/LayerEditor`` - Modul pro zobrazení a úpravu vrstev * ``src/LayerEditor`` - Modul pro úpravu konfiguračních souborů * ``src/lib`` - Modul s knihovnami používanými ostatními moduly * ``testing`` - Automatické testy Kontrola kódu ------------- Pro kontrolu se používá `pyLint `_. V hlavním adresáři každého modulu je soubor pylintrc, v kterém se píší pravidla pro vyjímky. Další vyjímky je možné napsat na začátek souboru, nebo nad vyjmutý řádek. Pravidla pro tyto vyjímky budou vznikat během vývoje a budou zapisovány do :doc:`samostatného souboru `. Bohužel s kontrolou kódu nemám zkušenosti a některé požadavky vyplynou až během vývoje. Proto zde popíši oblasti, na které by jsem se chtěl při kontrole kódu zaměřit a to co nekontrolovat vyplyne z porovnání poměru režie/přínos. To co nebude odpovídat mé představě o programování vyřadím. Bohužel zatím mám spíše dojem, že to nabízenými nástroji nedokáži udělat dostatečně adresně, aby zůstalo zachováno i co se mi líbí. Přehled pylintem kontrolovaných oblastí (lze použít pro vypnutí testu) je `zde `_. **Odsazení** V Pythonu asi nezbytnost. **prázné znaky na konci řádků** Je to dost otrava * *zjistit zda to může něčemu vadit* * *zjistit zda to něco neumí udělat automaticky* **Pravidla psaní kódu** Jednotná pravidla psaní kódu jsou hezká a asi i něco zvýší přehlednost kódu. Sice to není nijak zvlášt důležité, ale předpokládám že po několika kontrolách pylintem přejdou do krve a nebudou moc zdržovat. Pylint používá konvenci `PEP 0008 `_ **Konvence pojmenování souborů, tříd, proměnných ...** Pylint pro kontrolu názvů používá tuto `konvenci `_. O tomto platí to samé jako o předcházejícím. Mě nedělá problém číst kód napsaný jakoukoliv konvencí, spíš jí mám problém udržet. Doufám že pomocí pylintu bude můj kód, co se týká jednotnosti pojmenování, konzistentní. Škoda že to neumí hledat české názvy. **Kontrola použití lokální proměnné (_xxx) jiného modulu** Python nemá žádnou přímou cestu jak schovat proměnnou. (Jedině jí dát do souboru který je schovaný pomocí __init__.py) Osobně si myslím že bez nějaký formy ``zapouzdření`` to větším projektu nejde. Proto bych poprosil o důsledné rozlišení a označování lokálních proměnných pomocí ``_``. A doufám že chybu ``protected-access (W0212): Access to a protected member ...`` nikde neuvidím. Jen kromě testů, kde je testování lokálních proměnných praktické. **Starý styl vytvoření třídy** super-on-old-class (E1002) * *s někým se poradit a zjistit co to dělá* Dokumentace ---------------------- Dokumentace je psaná v `reStructuredText `_ a do finální podoby generována pomocí `sphinx `_. `reStructuredText `_ je docstring formát a `sphinx `_ pak umožnuje dodat pěkné formátování textu a vygenerovat požadovaný formát dokumentu. Generovat celou vývojářskou je možné z adresáře ``doc/`` pomocí make a požadovaného formátu. Například:: make html Dokumentace se skládá z uživatelské příručky, organizačních pokynů pro vývoj (v adresáři doc/organization) a z dokumentace samotných zdrojových kódů. Ta je automaticky generována po jednotlivých GeoMop modulech pomocí sphinx modulu `sphinx-apidoc `_ příkazem umístěným v ``Makefile``. `sphinx `_ není úplně jednoduchý nástroj na osvojení a je primárně určený na psaní dokumentace obecně. Naopak jako nástroj pro generování dokumentace ze zdrojových kódů není ideální a má mnoho much. Ale alternativy již nejsou zrovna aktivně vyvíjený a `sphinx `_ následně můžeme použít i na psaní uživatelské dokumentace. Generování dokumentace při push +++++++++++++++++++++++++++++++ Pro automatické generování dokumentace lze využít git hook ``pre-push``. Skript, který vygeneruje a pushne vytvořenou dokumentaci je umísťen v adresáři ``resources/development``. Pro použití je potřeba ho po naklonování repozitáře přesunout mezi git hooks, které se mají vykonat. .. code-block:: bash cp resources/development/pre-push .git/hooks/ chmod +x .git/hooks/pre-push Testování kódu po sobě ---------------------- Kód je nutné otestova kompletně a pokud víme že ovlivní i jiné části programu, pak i ty. Tam kde jsou psané kompletní testy stačí zběžně, v jiném případě by mělo být testování kompletnější. Testování - automatické testy ----------------------------- Pro psaní automatických testů je použit `pyTest `_. Testy je možné lokálně spustit z testing adresáře příkazem:: RunTests.sh UI testy qt částí aplikace je možné dělat pomocí qt knihovny `QTest `_ (Jen Qt dokumentace). Testování je popsáno `v tomto článku `_. V budoucnu je třeba spouštět testy automaticky po každém poslání do gitu nejlépe na deployi ve virtuálním prostředí. **Co se musí aut. testovat**: * přítomnost souboru v prostředí (z každého souboru zavolat nějakou funkci) * pokud je kód souboru závislý na nějakém resourci, knihově, nebo na něčem jiném, pak otestovat jejich přítomnost (zavolat část kódu, která danou závislost načte, nebo kde proběhne inicializace) * pokud jde o qt třídu, která obsahuje signál, pak otestovat signál **Co je dobré aut. testovat**: * Psaní automatických testů může být činnost, jež ušetří mnoho práce v budoucnosti, naopak muže být i velmi časově náročné a výsledek nevalný. Něco se testuje lépe a něco hůře. Na každém z nás je aby našel tu hranici, kde je to výhoddné. * Některý kód vede na něco jako úplné testy. Například implementujeme-li něco, co se může během vývoje (přidávání nové vlastnosti) lehce rozbít. Přičemž lze relativně lehce otestovat, že se nezměnila již nainplementovaná část. Pokud tomu tak je, určitě se o takovýto test pokusit. Do popisu třídy se pak poznačí, že jsou k ní k dispozici úplné testy Požadavky na vývojový PC ------------------------ Vše je psané pro Linux. Pokud by se mělo vyvíjet i na window, je nutné tam nainstalovat maketool a asi napsat nějaké alternativy k sh skriptům, ale ten je použit jen pro testy. Pokud by se našel někdo, kdo by chtěl vyvíjet na windows, je to v zásadě vítané, ale bude to znamenat vyřešit a zdokumentovat instalaci prostředí a přidání alternativních skriptů. Požadavky: * Python3 (včetně pip) * PyQt5 (včetně QScintilla a QWebKit) Instalace Python závislostí +++++++++++++++++++++++++++ Pro vývoj i běh se doporučuje používat virtuální prostředí, více viz `uživatelská dokumentace <../install/linux_installation_guide.html#virtual-environment>`_. Pro instalaci závislostí potřebných k vývoji aplikace lze použít následující příkaz:: pip install -r requirements-development.txt IDE --- Je možné používat IDE dle uvážení. Projektové soubory se do Gitem neverzují. Každý je zodpovědný za to aby mu to fungovalo na jeho Počítači. Možnosti: * Eclipse + `PyDev `_ - netestoval jsem, eclipse nemám rád * `PyCharm `_ - měl problémy s qt a nenašel jsem rychle přijatelné řešení , ale jinak docela dobré * `Eric IDE `_ - není s ním úplně jednoduché začít vyvíjet, ale když si na něj člověk zvykne ... . Tento nástroj budu používat asi já, takže budu schopný poradit a asi v něm půjde i generovat z docstringů i bublinková nápověda pro náš kód. Build ----- * *rozhodnout jaké instalační balíčky a systémy podporovat a dopsat*