search

ul-fmf / nadlogar

Spletna storitev za generiranje nalog
https://www.nadlogar.si
MIT License
18 stars 20 forks source link

Dokumentacija obstoječih nalog #50

Closed matijapretnar closed 3 years ago

matijapretnar commented 3 years ago

V #20 piše, da moramo ločiti med docstringom, ki naj bi bil namenjen razvijalcem, ter dodatnim atributom help_text, ki naj bi bil namenjen učiteljem in bi se prikazal v spletnem vmesniku. Predlagal bi, da to dvoje združimo v docstringu. Namen vsakega izmed teh razredov je, da generirajo naloge določenega tipa, in prva stvar, ki si jo vsak želi videti, je opis naloge. Kakorkoli se trudim, mi ne uspe najti primera, kjer bi razvijalec v nasprotju z učiteljem želel videti kaj drugega. Če so že kakšni tehnični detalji algoritma, bi bolj sodili v komentar (ali morda dokumentacijski niz) metode generate.

Closes #20

jureslak commented 3 years ago

Razlog, da to ni v docstringu, je, da se lahko to stvar prikaze na strani (kot text/html), medtem ko imajo lahko docstringi predpisan format (za sphinx ali kaj podobnega), ki ne sodi na spletno stran. Če že, bi rekel da potem to sodi samo nekam drugam, kjer lahko prosto določamo obliko, ne pa v docstring, kjer je s konvencijami to že določeno. Še ena pripomba je, da se docstringov ne da (oz. ni lepo) generirati dinamično, medtem ko z metodo to lahko počneš.

V V tor., 27. jul. 2021 ob 10:28 je oseba Matija Pretnar < @.***> napisala:

V #20 https://github.com/ul-fmf/nadlogar/issues/20 piše, da moramo ločiti med docstringom, ki naj bi bil namenjen razvijalcem, ter dodatnim atributom help_text, ki naj bi bil namenjen učiteljem in bi se prikazal v spletnem vmesniku. Predlagal bi, da to dvoje združimo v docstringu. Namen vsakega izmed teh razredov je, da generirajo naloge določenega tipa, in prva stvar, ki si jo vsak želi videti, je opis naloge. Kakorkoli se trudim, mi ne uspe najti primera, kjer bi razvijalec v nasprotju z učiteljem želel videti kaj drugega. Če so že kakšni tehnični detalji algoritma, bi bolj sodili v komentar (ali morda dokumentacijski niz) metode generate.

Closes #20 https://github.com/ul-fmf/nadlogar/issues/20

You can view, comment on, or merge this pull request online at:

https://github.com/ul-fmf/nadlogar/pull/50 Commit Summary

  • Generatorjem dodal docstring in help_text na poljih

File Changes

Patch Links:

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/ul-fmf/nadlogar/pull/50, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAKUPHRDBJSZTDSIL4CFFRTTZZU2DANCNFSM5BBXIOFA .

matijapretnar commented 3 years ago

Kakšen HTML in dinamično vsebino si imel v mislih? Jaz sem mislil, da bi bil vse skupaj samo en stavek, ki se napiše zraven imena naloge (to me spomni, da je na modele treba dodati še verbose_name), primere nalog pa bi tako ali tako naredil in prikazal ločeno.

Kaj pa, če na spletni strani prikažemo samo prvo vrstico docstringa (oz. do prve prazne vrstice), kjer smo dogovorjeni za golo besedilo (pri razredih tako tudi ponavadi je), v preostanku docstringa pa so lahko tudi morebitne druge stvari, namenjene razivjalcem?

matijapretnar commented 3 years ago

Bom zaenkrat naredil po svoje, da se stvar premakne, ko se bo pokazala potreba, pa brez težav spremenimo.