Kpimark Extension API

Dobrý deň pán doktor @sergej.chodarev.

Najprv mi dovolte odkázať Vás na samostatný branch diff

Implementoval som návrh rozširovania Kpimarku pomocou init.py súboru v kurze a chcel by som vedieť Váš názor na predkladané API.

Pri návrhu som vychádzal z podmienky poskytnutia čo najväčšej slobody používateľom a pritom zachovania jednoduchej implementácie. Z týchto dôvodov som navrhol jediný dekorátor @register_renderer, ktorý by mal poslúžiť pre registrovanie ľubovoľného renderera. Myslím, že z príkladu init.py súboru to bude najjasnejšie:

from it4kt.kpimark.blocks.admonition.base import AdmonitionBlock
from it4kt.kpimark.extension import register_renderer
from it4kt.kpimark.renderers.html import KpimarkHTMLRenderer
from it4kt.kpimark.validation.validator import Validator


class SecondExample(AdmonitionBlock):
    ALERT_TYPES = ["second example", "druhý príklad"]

    @classmethod
    def start(cls, line):
        return super().start(line, cls.ALERT_TYPES)


@register_renderer(KpimarkHTMLRenderer)
class HTMLRenderer(KpimarkHTMLRenderer):
    TOKENS_EXTENDED = [SecondExample]

    def render_second_example(self, token):
        return self.render_admonition(token, "Second Example", "example")


@register_renderer(Validator)
class ExtendedValidator(Validator):
    TOKENS_EXTENDED = [SecondExample]

    def validate_second_example(self, token):
        pass

Používateľ implementuje požadovaný token a následne vytvorí inštanciu nového prekladača, ktorá je počas behu programu použitá namiesto triedy uvedenej v argumente dekorátora.

Týmto spôsobom je zachovaný funkčný live-reload nástroja pri uložení zmeny v súbore init.py.

Používateľ si taktiež môže zvoliť, či je potrebné implementovať aj vlastnú validovaciu funkciu alebo nie. Pokiaľ token nepožaduje validáciu, môže celý nasledujúci fragment kódu vynechať.

@register_renderer(Validator)
class ExtendedValidator(Validator):
    TOKENS_EXTENDED = [SecondExample]

    def validate_second_example(self, token):
        pass

Používateľ môže vďaka tejto implementácii taktiež pozmeniť renderovanie niektorého z tokenov bez nutnosti prepisovania tokenu samotného alebo pozmeniť iba validáciu niektorého z tokenov, pokiaľ to naozaj potrebuje.

Vďaka tejto implementácii si dokonca môže používateľ implementovať aj vlastný výstupný formát keďže za vzhľad výstupu je zodpovedný jedine renderer (z pohľadu prekladača Kpimark, ale pre nástroj it4kt-builder by samozrejme boli potrebné ešte nejaké úpravy témy a tak ďalej).