SPHINX - Python documentation generator #337
Labels
No Label
app-basic
app-ckan
app-crisiscleanup
app-cts
app-decidim
app-dhis2
app-frontlinesms
app-gnuhealth
app-kanboard
app-mifosx
app-motech
app-odoo
app-opendatakit
app-pandora
app-sahana
app-seeddms
app-sigmah
app-taarifa
app-ushahidi
critical
CZ
documentation
Doing
enhancement
GMaps
info
Mapbox
needinfo
new-app
OSM
performance
QGIS
regression
suggestion
To Do
upstream
No Milestone
No project
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Disassembler/Spotter-VM#337
Loading…
Reference in New Issue
Block a user
No description provided.
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Dotaz: Mohla by dokumentace být ve formě nějak podle http://www.sphinx-doc.org/en/master/
Případně pokud máte něco lepšího, nechám se poučit.
Cílem je aby dokumentace nebyla jen nějaký plaintext/markdown. Nechám na vás, zatím nevím na jakou formu se mam těšit.
changed milestone to %3
changed the description
No moment, ale Sphinx je jen nějaký plaintext/markdown. Konkrétně používá formát reStructuredText (rst), což je značkovací jazyk s omezenými funkcemi, úplně stejně jako je Markdown. Sphinx se používá převážně pro dokumentace pythonovských modulů a programových rozhraní, ale je možno jej samozřejmě použít pro cokoliv jiného.
Sphinx je "lepší" díky svým nástrojům, které umožňují například automatické generování kostry stránky na základě komentářů v kódu à la Doxygen nebo Javovský JavaDoc a tím, že se celá dokumentace dá snadno exportovat do jiných formátů (HTML, PDF, ...). Přirovnal bych ho k Markdownu, který někdo chtěl předělat na TeX, ale po dvou dnech ho to přestalo bavit. Vzhledem k tomu, že my máme kódu naprosté minimum (a takového, který bude muset používat někdo jiný nemáme vůbec žádný) a budeme chtít dokumentovat hlavně postupy, ovládání, architekturu a takové věci, automatizace nám tu nijak zásadně nepomůže.
Tady na GitLabu a hromadě dalších míst se wiki píšou Markdownem a konkrétně z GitLabu se z nich externími nástroji (např. Wiki2PDF) dají PDF vyrábět taky. Obecně se dá vyrábět z čehokoliv cokoliv, protože jde jen o nějaký značkovací jazyk, ale je k tomu potřeba najít vhodný nástroj a v tomto případě to jde pár kliknutími. Osobně píšu v Markdownu už prakticky všechno, kvůli přenositelnosti. Markdown je možno vyrenderovat téměř v jakémkoliv slušnějším textovém editoru nebo webové službě, což se o rst říct nedá. Například zde na GitLabu s Markdownem můžete hned nahlédnout jak bude váš počin vypadat. Pokud budeme psát v rst, budeme si muset pomáhat nějak jinak. Nicméně prý existují i nástroje, které naučí Sphinx žrát Markdown syntaxi, ale už je to rovnák na vohejbák.
Sphinxu se nebráním. Pokud chceme mít veřejně přístupnou dokumentaci úplně oddělenou od GitLabu, tak to není vůbec špatný nápad, protože nám umožní vygenerovat statické HTML stránky (což teda z Markdownu při použití nějakého nástroje třetí strany můžeme taky). Dalšími alternativami by byly jakékoliv jiné wiki-like systémy (DokuWiki, MediaWiki, MoinMoin atd.)
Mám se tedy začít učit Sphinx nebo raději najít způsob jak vyrábět exportovatelnou dokumentaci ze stávajícího Markdownu? Máte nějaké další cíle a očekávání kromě toho, aby dokumentace nebyla jen nějaký plaintext/markdown, což stejně bude?
jasný... to jsem asi nejasně napsal. Markdown jako takový pro obsah mi nevadí a vesměs vyhoví pro úpravu obsahu. Šlo mi o celkově prezentovanou strukturu v které se bude používat nějaká taková úprava. Tj. nějaké "site" kde lze strukturovaně rozvíjet dokumentaci. Aby to nedopadlo jako jsem to už zažil se Skřivánkem a jeho Google docs nebo jinými Wordy.
Co se týče publikovatelnosti, tak vesměs nejsem proti, spíš celkově ještě nemám domyšlenu úplnou koncepci šiřitelnosti informací ke koncovým uživatelům. A umístění kde to bude... Předpokládám že to budou čistě technické info, takže nejspíše blízko zdrojovým kódům. Tohle rozhodnutí se jistě dá udělat později.
Spekuloval jsem chvíli i s myšlenkou, že dokumentace by byla volitelně instalovatelná do VM, ale to nevím.. případně napište co si o tom myslíte.
Díky.
No pokud použijeme Sphinx a vygenerujeme statické HTML, tak by dokumentace byla volitelně instalovatelná a funkční málem i na kalkulačce nebo oscilátoru, takže proč ne.
A ano, strukturu a navigaci má Sphinx docela vymakanou, té by nejspíš nebylo úplně triviální dosáhnout s nástroji pracujícími přímo s čistým Markdownem. Zkusím tedy kouknout jaké nástroje pro existují, pohrát si s nimi (včetně Sphinxu), nakrmit je tím, co máme a uvidím jak moc přes ruku to bude. Při nejhorším se zas něco naučím.
Oukej. Padám samým údivem na prdel. Sphinx je vážně vymazlenej. Nejen že ten markdown ve stávající verzi sežere bez větších problémů (doinstalovat jeden modul a nastavit jeho použití pro daný typ přípony), ale navíc si ho proleze a z nadpisů si vytvoří obsah. Dále umí vytvářet i vícejazyčné dokumentace a ještě k tomu si vytváří i jednoduchý vyhledávací index, takže je na statických stránkách možno s pomocí automaticky generovaného skriptu vyhledávat. Myslím, že další nástroje už nemá cenu ani zkoušet, tohle je bomba.
Příklad renderu stránky s Markdown dokumentací pro jeden z našich balíkovacích nástrojů:
Takže ano, jsem rozhodně pro mít dokumentaci řešenou Sphinxem.
Paráda.. :)
Sphinxem vytvořená technická dokumentace s mobilně responzivním ReadTheDocs tématem vygenerována a šoupnuta na https://dl.dasm.cz/spotter-doc/index.html, jak jsem zmínil v #290.
Tady už se jen zeptám jakým způsobem si přejete, abychom ji udržovali?
Varianta 1 je, že se použije wiki a jednou za čas se extrahuje, ostrukturuje a vygeneruje z ní HTML. Výhoda je, že se nám nebude dokumentace motat mezi kódem a budete ji moci snadno editovat v GitLabovém editoru. Nevýhoda je, že struktura samotná se před vygenerováním bude muset zkontrolovat a upravit ručně, protože ta se Sphinxem nebude kompatibilní (mohla by být, ale pak by na wiki vznikaly podivné indexové stránky v reStructuredText formátu).
Varianta 2 je, že v základním repozitáři vytvořím podadresář
_doca tam to budu sypat. Tím pádem budu moci statické HTML vytvářet lusknutím prstu, ale vy budete mít ztíženou editaci. Na druhou stranu se Vám to nebude motat mezi Vašimi poznámkami na wiki a odliší se tak hotová publikovatelná dokumentace od věcí co jsou stále work in progress.Zásadní benefity nebo problémy nepřináší ani jedna z variant. Když se trochu uklidí stávající wiki, varianta 1 bude asi z hlediska spolupráce a četnosti změn praktičtější.
Vypadá to super, takže paráda, na tomhle se dá dobře pokračovat.
K udržování:
ještě dlouhou dobu budete mít k dokumentaci a její úpravě přístup pouze vy. Další potenciální vývojář(i) zatím jen k čtení. Takže způsoby aktualizace se usadí jak vám budou vyhovovat, předpokládám že později i někomu jinému, včetně mě.
Varianta 1 - pro mne jako BFU to zní dobře, jen teď nevím jak se to popere se současným obsahem wiki. Ano, teď tam je nasypáno víc věcí najednou. Je možno to nějak lépe oddělit, nebo to bude v jednom chumlu?
Varianta 2 - taky mi příjde jako dobrý návrh, já sám neplánuju zásahy do dokumentace, dokud máte hlavní slovo ve vývoji.
Berme ale v úvahu, že další člověk dostane také zadání doplnit dokumentaci o svůj díl práce. (Mapy, frontend) Bude to OK?
jsem jen lehce víc pro 1.
No idea u 1 je taková, že místo stávajícího chaosu
Vznike struktura
Já pak přijdu, checkoutnu si celou wiki (je to git repozitář jako každý jiný), smažu si lokálně Other a zbytek dám sežrat Sphinxu, z něhož vypadne statické HTML, které můžu obratem nahrát někam k Vám na web nebo nabalit do APK balíčku pro instalaci do VM, o čemž jsme se bavili před pár dny.
Takže jestli mi to takhle odkývete, tak jdu na to, to co je teď obsahem celé wiki přetáhnu do Other, svou technickou část strčím do Technical documentation a v User documentation budu očekávat veškerou publikováníhodnou uživatelskou dokumentaci.
Ano, to je OK, prosím upravte to takto.
pro zajímavost - asi velmi blízkou strukturu dokumentace má BIBBOX https://bibbox.readthedocs.io/en/latest/
a celý ten admin je něco, kam by mohl Spotter VM směřovat. https://bibbox.readthedocs.io/en/latest/admin-documentation/
(zvláštní pocit, že bez mé předchozí znalosti těchto řešení jsem s vámi došel téměř k něčemu velmi podobnému. Třeba tam objevíte i nějaké know-how)
Oukej. Ta GitLab wiki je celkem zlá. Až tak, že je i nebezpečná.
|má ale v linuxu speciální význam (pipeline) a ve Windows pro jistot vůbec není povolen, takže repozitář s wiki se na nich nedá ani stáhnout.Necháme tedy wiki jen na poznámkování a work-in-progress věti a publikovatelnou dokumentaci jsem nastrkal do podadresáře _doc v hlavním repozitáři. A tu titulek té Pandora stránky jsem oprostil o všechny podivné znaky.
Ok, Díky. K dokumentaci mi prosím řekněte, jestli je vhodné tam stručně zmínit i takové ty věci jak jsme si psali o logování a podobně. Klidně tam doplňte prozatím prázdné stránky do struktury, abychom na něco později nezapomněli.
Pak mi dejte vědět, kdy budete hotov s touto fází a s nějakým aktuálním stavem VM, já si teprv pak začnu dopisovat s p. Nétekem. Kdyby mne neodmítl okamžitě, jsem ochoten mu ukázat odkaz na dokumentaci, lokální VM a pak se teprv uvidí kam mne pošle.
Určitě. Vhodné je zmínit všechno. Nevíme jaké znalosti a zkušenosti bude náš potenciální čtenář mít.
...eeeh. Jsem rád, že při tom všem přebíhání od jedné věci k druhé udržím alespoň moč, ale myšlenku už ne. Co jsme si psali? Alespoň rámcově, pokud to zrovna nenajdete.
V ToDo teď máme veskrze designové věci a pak dvě záležitosti k Sahaně, takže můžu vyrobit nový build VM ještě dneska. Seženu si nějaké kafe a jdu na to.
V naší dokumentaci by se mohlo objevit:
issue o licencích https://git.spotter.cz/Spotter-Cluster/Spotter-Cluster/issues/285
Zatím stačí malá podstránka o licencích, kde by měl být jmenovitě oddělený
issue o logování je tady https://git.spotter.cz/Spotter-Cluster/vmmgr/issues/1#note_2088
Stačí asi zmínit ty limity jak se logy zapisují, obnovují
issue Ping/pong https://git.spotter.cz/Spotter-Cluster/Spotter-Cluster/issues/289
Pak bude asi něco víc o celém tom prvním přednastavení VM
issue https://git.spotter.cz/Spotter-Cluster/Spotter-Cluster/issues/273
Zjednodušené anonymní rozhraní ...
Možná ještě něco objevím, co jsme si psali.
Chtěl jsem do něj ještě implementovat oficiální podporu pro VPN a vzdálený přístup, kdybychom zase potřebovali lovit nějaké vzdálené bugy, a nějak jsem do to zabrousil a ještě nevybrousil, protože na mě stihly napadat nějaké pracovní
sračkyzáležitosti. Tak zatím jen sneak peek. Zítra už bych to fakt měl dorazit.WireGuard v době kdy jste o návrhu VPN uvažoval ještě neexistovala - odbornou obcí je považována za mistrovský kousek, díky své jednoduchosti jak konfigurace, tak celého programového kódu, výběru state-of-the-art algoritmů a výkonu - čtení tu: https://www.wireguard.com/ - kousky týkající se nasazení v naší VM zdokumentuji i u nás.
Za výtah věcí k dokumentaci díky, po zbuildnění a uploadnutí image se do toho pustím.
Paráda... já myslím že VPN bude fajn nástroj.
S VM si rád zase pohraju, časově si to nastavte jak to zvládnete,
moje další reakce, případně kroky budu hlásit.
Technická dokumentace na https://repo.spotter.cz/doc/ aktualizována o všechny novinky a změny za posledního tři čtvrtě roku. Prosím o nějaké zevrubné projití (je tam spousta implementačních detailů, takže podrobné od Vás určitě nevyžaduji) a případné vypíchnutí bodů, které tam nejsou a rád byste je tam ještě viděl. Za tu dobu už trpím profesní slepotou, takže jsem si celkem jist, že se najde spousta věcí, které by tam nejspíše měly být, ale pro mě jsou tak strašně zřejmé, že by mě ani nenapadlo se o nic zmiňovat, takže pokud Vás nějaké takové napadnou, podělte se.
Jak vyžehlíme dokumentaci, pošlu takový ten nepříjemný dokument s ciframi.
Ok, projdu. dám info.
Dílčí poznámky... ještě doplním
na straně https://repo.spotter.cz/doc/toolchain/vmmgr-overview.html
u Application manageru nějak kulantně naznačit, že to je pouze pracovní verze frontendu. Že je pouze v češtině a v této fázi nemá smysl ji překládat.
na straně https://repo.spotter.cz/doc/applications/map-services.html
Crisis Cleanup v.2 Google Maps (imho autor už nikdy neumožní aby fungoval s jeho serverem)
Crisis Cleanup v.3 OSM (imho co s tim skutečně bude, je ve hvězdách)
ostatní nezprovozněné apps asi v této situaci zbytečné.
zmínka a odkaz o POSM - nefunkční, projekt POSM vymřel. Odkaz odstranit.
na straně https://repo.spotter.cz/doc/applications/sahana.html
nefunkční odkazy
mentioned in commit
553930da0dKomentáře zapracovány. Pro správné zobrazení bude možná nutno ručně refreshnout stránku přes F5, Sphinx cachuje docela agresivně.
Za tu zmínku o nefunkčních odkazech díky. To je něco, co jsem chtěl před odevzdáním ještě projít a už jsem na to v jedenáct večer neměl myšlenky a zapomněl na to.
pokračuji v poznámkách... ještě doplním (nestíhám real life)
Na straně
https://repo.spotter.cz/doc/applications/sahana-configuration-report.html
je v úvodu věta: The configuration has been tested on Sahana Eden version 56afb71 (2017-08-31 01:10:50) using default template.
Pokud jste tedy dělal kontrolu této konfigurace, případně změny, mělo by být nové datum. Namátkou jsem zahlédl, že u https://repo.spotter.cz/doc/applications/sahana-configuration-report.html#localization-settings zůstal starý výčet jazyků bez polštiny. Vyřešit můžete tak, že buď tyto kusy kódu vůbec v reportu neboudou, nebo budou aktuální. To se týká i dalších kusů kódu v tomto reportu, který nebyl námi ovlivněný a námi doplněný pro účel VM.
Prosím ještě odstranit stranu Sahana configuration report z wiki.
Wiki v Gitlabu - Pokud ve Wiki spatříte nějaké zbytečné, nebo zastaralé informace, taky prosím odstranit.
Původně jsme chtěli ve wiki udělat strukturální změny stran. Diskutováno někde. Pomůžete mi?
Obsah wiki případně doplním / změním / odmažu sám. To taky musím projít.
FrontlineSMS - zde by bylo vhodné zmínit, že tato cloudová verze s otevřenou licencí (v.2.0.x) už není výrobcem dále vyvíjena, tedy na VM nebude dále upgradována. Česká lokalizace je dostupná pouze na VM. Výrobce poskytuje ve své nové verzi pouze SaaS s desktopovým klientem.
Pokud nemáme, prosil udělat fork FrontlineSMS na můj github jako zálohu, kdyby je náhodou napadlo to později smazat.
Česká lokalizace Sahany a dalších SW na VM.
Vím, že jsem po Vás chtěl omezení jazyků jen na ČJ a EN, teď přemýšlím, jestli z důvodů použití mimo ČR raději zapnout všechny ostatní jazyky.
U aplikací, kde je česká lokalizace součástí zdrojového kódu asi nemusíme zmiňovat nic.
U Sahany jsme také dělali drobné úpravy pro český region v configu, tj. přidání české měny, možná ještě něco.
U Sahany, FrontlineSMS, kde je ČJ lokalizace pouze na VM, by bylo vhodné zmínit, že ČJ není součástí zdrojového kódu. (Aby se někdo nedivil, hlásit se to musí).
Nedělal. Je to ta samá stránka jako na wiki, jenom přeformátovaná pro Sphinx. Aktualizaci můžu udělat, ale varoval jsem, že to bude na dlouhé lokte.
Odstraněno.
No to bylo přímo tady v tomto ticketu. Nicméně z toho salátu na wiki není úplně jasné, co jsou interní poznámky pro Vás a co chcete mít v technické dokumentaci (uživatelskou zatím neděláme), takže to proberte a popřesouváme to.
Zdokumentováno, forknuto a vzhledem k tomu, že ten fork je celkem na prd, tak i uploadnuta zdravá verze balíku jako "release".
U Sahany jsme dělali hromadu modifikací, máme na to celý Spotter template, ale ten nepovažuju za nijak stálý a dokumentováníhodný. Čeština jde mimo templaty, takže tu jsem zdokumentoval. Na zapínání dalších jazyků kdyžtak vytvořte separátní ticket.
A ještě koukám, že musím zdokumentovat workaroundy u crisiscleanupu, openmapkitu a pandory. Achjo.
na CC v.2 se s prominutím viserte asi :)) podle mne je nemožné s tím cokoliv v budoucnu udělat. Ledaže by ve vašem workaroundu bylo něco jako dissassembler-fu, to by pak mělo trochu hodnotu. Jinak fakt nevím... Co myslíte?
Za úpravy díky, ještě napíšu, abyste nedělal něco zbytečně :)
k té wiki... nyní to je interní wiki a dlouho ještě interní zůstane. Binec přiznávám, ale chtěl jsem ho jen sdílet tak, aby to bylo dostupné v projektu více lidem. Kvuli zpětné vazbě. Jinak bych si různé odkazy dokázal syslit i soukrommě.
Pokud bych zvládl nastavit víceúrovňovou strukturu stran, tak to udělám aby to nebylo jen v první úrovni.
Veřejná wiki s méně info by teoreticky vznikla za dlouhou dobu až v situaci, kdy by se projektem někdo zabýval. Jinak je to zbytečné a podle vašeho zjištění to má i nějaká bezpečnostní rizika.
Dokumentace workaroudů k aplikacím:
Nicméně... po průběžném průzkumu Decidim a jiných aplikací vč. Karrot kterou jste neřešil a CoopCycle bych se jimi mohl později zabývat, takže Coopcycle průzkum nezahazovat.
Omlouvám se za můj nepříliš uspořádaný feedback, pohybuji se mezi více počítači, ale jen u vlastního PC doma mám někdy kolem půlnoci klid na hlubší přemýšlení. Zbytek dne je to neuspořádané a pak ze mne padají nesrozumitelné věty.
Zdokumentováno. CC 2 mi připadá funkční, to žádnou cloudovou část nepotřebuje. Jestli je ovšem použitelné v praxi je věc jiná.
Právě proto jsem si nebyl jist tím, co všechno mám přestěhovat do "oficiální" dokumentace a ptal se na to. Prošel jsem si ty stránky a co mi připadlo dostatečně oficiální nebo co mi pomohlo rozpomenout se na nějaké implementační detaily jsem tam šoupnul.
Průzkumy nikdy nezahazuju. Zvlášť ne, pokud mi jejich prozkoumávání zabralo několik hodin. Jen je uklidím někam na hrobeček. Dokonce i ten dokument k Horde ještě mám a nehodlám se jej hned tak zbavovat.
večer se na to doma podívám. Celkově je to zpracované velmi pěkně, a věřím, že když to bude někdo zkoumat, tak se dozví maximum :) takže teď nevím nic zásadního k tomu.
Když jste dělal ty testy kódu... Váš kód dopadl cajk, ale něco jste zmiňoval, že jste si vědom omezení. Tak jen pro jistotu, jestli jste to někde zmínil, jestli to tam je, tak bych to asi našel, ale trvalo by mi to strašně dlouho.
Ještě hloupý dotaz: V tom počátečním procesu přípravy balíčků si nejsem úplně tak jist jak se to děje. To je činnost, která se děje adminem na jím zvoleném repozitáři a vyžaduje nějaký námi navržený setup? Je tam zmíněn princip stažení z orig repo, zabalení, uložení do adresáře na serveru aby se pak k němu mohla VM připojit a stáhnout. Případně instrukce / limity za jakých podmínek se lze pustit do update nebo vzniku nového kontejneru s novou app. Uložené balíčky mají konkrétní verzi, tak aby to i třak bylo chápáno, že se instalují tyto buildy, ne zcela aktuální buildy.
Je mi jasné, že podmínky apps jsou dány jejich dokumentací, to nemusíte kopírovat.
U Sahany probíhá nějaký proces buildění ve web2py a to se děje v tom balíčkovacím procesu kdy přesně?
Jestli myslíte ten SonarQube, tak to byly vesměs věci, které byly očividně úplně ujeté. Jako třeba že na řádku, kde se zjišťovalo, zda byl předán HTTP nebo HTTPS protokol to varovalo, že HTTP je nezabezpečené. Nebo že na řádcích, kde se něco hashovalo to varovalo, ať si zkontrolujeme, že je použita silná hashovací funkce a takové chobotiny. Kdyby se mělo něco takového dokumentovat, tak je to stejně potřeba dělat v kódu, protože tam na to ten linter ukáže. Nikdo se nepoletí koukat do dokumentace, jestli je warning XY ve funkci bž() očekávaný.
Nerozumím úplně na co se ptáte. Počáteční proces přípravy balíčků je buildění image, což se děje přes
spoc-image buildza pomoci těch souborů s build direktivami. Ty si ten, kdo ty image vytváří, napíše dle svého. Pokud ty vybuilděné image chce i distribuovat, tak pak si vygeneruje pár kryptografických klíčů a s pomocí soukromého přesspoc-image publishaspoc-app publishvytváří podepsané archivy. Ty někam nahraje (to "někam" je ten repozitář - není k němu potřeba žádný speciální software, je to prostě adresář na webovém serveru) a když je odtamtud chce nějaký uživatel stáhnout, tak k jejich ověření potřebuje veřejný klíč toho, kdo je podepsal. Klíče se momentálně konfigurují v konfiguračním souboru, klikátko na ně nemáme, protože ještě chvíli neočekáváme, že bychom měli repozitářů víc než jeden.Do update nebo vzniku nového kontejneru se lze pustit kdykoliv a limity nejsou.
Verzované jsou v podstatě jen aplikace, u kterých se vždy instaluje poslední dostupná verze. Image sice ve svém názvu něco jako číslo verzi obsahují, ale ta slouží pouze jako unikátní identifikátor pro rozlišení člověkem, který sestavuje kontejnery a na nic jiného nemá vliv. Připadalo mi deskriptivněšjí "alpine3.11_3.11.4-200202" a "alpine3.11_3.11.5-200403" než "20990665367ed4a7992681fcd44da693d6522e0c7c9549fd5e3ac5a35e8ba565" a "17e77482af04da8e68195f25ff9ab870cedec7d5192b35951940b50b1122863a", jako to dělá Docker. Tohle je v dokumentaci pro buildery zmíněno.
Taky nevím, co tím myslíte. U Sahany se nahážou všechny potřebné soubory (python, web2py, sahana atd) do image a ten se zabalí. Tam se buildí maximálně nějaké moduly pro python. Odděleně od něj se zabalí instalační skripty a metadata, ve kterých je mimo jiné řečeno, které image jsou potřeba. Na straně uživatele se tohle všechno z metadat zase vyčte, stáhnou se ty balíčky, rozbalí, vytvoří se z nich kontejnery (u Sahany jeden aplikační a jeden databázový) a pak se spustí instalační skript, který to celé nakonfiguruje. V téhle fázi se vytváří a plní databáze, takže až teprve tady je poprvé spuštěn proces Sahany, která pomocí funkcí web2py frameworku čte konfiguraci template a plní data do databáze.
Kdybychom distribuovali databázi už naplněnou, budou balíčky mnohokrát větší a unikátní záležitosti jako klíče, hesla, GUIDy atd. nebudou unikátní.
k tomu SonaQube: aha.. ok.
k hloupému dotazu: aha, tohle už je mi jasnější, jen abych věděl že "není potřeba žádného softwaru" je zcela transparentní pro adminy kteří by to chtěli začít úplně znova jen podle dokumentace.
k Sahaně: už jsem si vzpomněl na slovo prepopulating, což mne strašilo v době mr. Skřivánka, neboť mi v procesu práce na Sahaně (myslím tím updaty při nějaké změně kódu) neustále upozorňovali, že jejich updaty vyžadují obtěžující proces prepopulating a proto ho nebudou dělat každou chvíli co si požádám abych viděl co vzniklo... kterýžto vy jste patrně dělal když bylo potřeba a bez takových keců.
Pro mne si tedy teď beru informaci, že nakonec jste připravil velmi šikovný skript, který to instalaci realizuje komplet. Případný bugfixing a následný prepopulating je věc vývoje na Sahaně. Ale ne věc čisté instalace Sahany z balíčků tak, jak se to dělá pro účel VM. Chápu to dobře?
OK, ještě si pročtu, co jsem vlastně napsal a kdyžtak upravím, aby to bylo srozumitelnější. Koukám, že některých větám by trocha kontextu navíc určitě neuškodila.
Přesně naopak. To je pouze věc instalace u koncového uživtele. To je právě to plnění dat do databáze. Dějí se tam dvě věci - migrace a prepopulace. Migrace se týká databázové struktury, prepopulace pak jejího obsahu, který se bere z template. A myslím, že Vás Mr. Skřivánek zase trochu povodil za nos, aby si usnadnil práci.
Jde o to, že některé updaty kódu změní její strukturu, takže pokud změny chcete aplikovat na stávající instanci, je nutno provést tzv. migraci (fskutečnosti se nic nikam nemigruje a prostě se updatuje databáze, ale říká se tomu tak u všech aplikací a to i v případě, že se "updatuje" z prázdné databáze). Při updatech se to dělá tak, že se ručně nastaví
settings.base.migrate = True, smaže se adresář s nacacheovaným bytekódem pythonu v Sahaně, pustí se stejný proces jako při iniciálním plnění, ten zjistí, že v databázi už něco je, tak jen aplikuje rozdíly a pak se zase nastavísettings.base.migrate = Falsea zkompiluje se nový bytekód, aby Sahana běhala svižně. Případně se dá ta volba nechat zapnutá a nastavit ještěsettings.base.debug = Truea v takovém případě jede Sahana v debug módu a pokouší se aplikovat změny okamžitě při každém požadavku, ale je kvůli tomu o hodně pomalejší.Tohle mě taky párkrát vypeklo a docela dlouho jsem nevěděl, jak to správně udělat, což je i důvod proč všechny nasazení aktuálních verzí Sahany doprovázel datový klystýr, takže jsem pokaždé instaloval do prázdné databáze. Teď už to vím a bude to dělat update skript při aktualizaci aplikačního balíčku.
Prepopulace je ale problém, protože ta se týká jen samotných dat, která nejsou nijak verzovaná, takže Sahana má volbu
settings.base.prepopulate, ale ta prakticky dělá jen to, že při každém requestu zkontroluje, zda existují data v databázi a pokud ne, tak ji naplní. Jakmile je databáze naplněná, nemá ta volba žádnou užitečnou funkci. No a jakmile je databáze naplněná, tak jediná možnost, jak ji prepopulovat znova jinými daty, je celou ji vyprázdnit (a k tomu ještě smazat souborovou cache tabulek, které si dělá Sahana) a celou naplnit znova, takže tady už je to mazání databáze mezi verzemi vcelku ospravedlnitelné.Obě operace zaberou maximálně 5 minut, ale je potřeba vědět, kam sáhnout. Když to člověk neví, tak jako jsem to v začátcích nevěděl ani já, pak je nejpřímočařejším řešením přeinstalovat celou Sahanu. Naprosto chápu, že se do toho ptáčkovi nechtělo, když ji měl nainstalovanou přímo na železe a nemohl pracovat se snapshoty.
aha, ok. To je zrovna případ, kdy neseznámený člověk tápe a zkoumá jak je konkrétní aplikace vymyšlená. Z toho co jste napsal by tedy stálo zato udělat buď odstavec v naší dokumentaci ve smyslu jak se to dělá s daty, když jsou-nejsou v Sahaně a je potřeba ji znovu sestavit. Popis této logiky zkracuje dobu tápání a omylů. Které někoho stojí čas, peníze, nervy nebo vše najednou.
Nebo alespoň dát odkaz na dokumentaci, jestli je to tam dostatečně rozepsáno.
S poznámkou, že toho je sice hodně, ale některé informace jsou spíše vývojové. (Jak už jsme všichni mnohokrát zjistili), Sahana je spíše vývojový framework pro cílové deploymenty. Naše práce je nadstavbou pro uživatelské deploymenty, která by měla adminům pomoci v rychlejším, nebo nezávislejším nasazení.
Obecněji co v dokumentaci není:
Celá technická dokumentace se věnuje hlavně architektuře a vytváření VM... Ok. Co myslíte, mělo by se někde objevit i popis co se může stát, když je vše běžící a uživatelé již pracují s app a mají data? Setkal jste se s nějakou havarijní situací která vznikla tím, jak jsou aplikace vymyšlené? Patří to k této dokumentaci, nebo spíš do interní wiki?
Něco z toho budou určitě sdělení kapitána Zjevného, ale možná že něco ne...? Uvažuji nahlas. Nemusíte odpovídat okamžitě.
closed via commit
547c3cf84f