search

inbo / dhcurve

An R package for automated modelling of diameter-height relations for trees
https://inbo.github.io/dhcurve
GNU General Public License v3.0
0 stars 0 forks source link

pdf-rapport ook via package toegankelijk? #52

Open leymanan opened 2 years ago

leymanan commented 2 years ago

Is er een mogelijkheid om het rapport "Rapport_PackageDHCurve.pdf" ook ergens toe te voegen? Ik zie dat er een Rmd-versie onder folder "man" staat (Handleiding.Rmd), maar misschien is een downloadbare pdf ook handig voor degene die niet gewend zijn om met R te werken?

(PS: vorig jaar kwam er steeds van alles tussen fietsen, maar nu wil ik met voorrang dit volledig afwerken; ik ben nu bezig met het uitschrijven van een workflow voor ANB-ers die niet gewend zijn om met R te werken)

leymanan commented 2 years ago

Ik zie dat er ook een html-versie staat onder docs/articles/Handleiding.html (met Handleiding.Rmd als source). Zit dat standaard in het package? Want ik zie de folder "docs" niet staan in de webversie van het package (https://github.com/inbo/dhcurve/tree/afwerking) Wellicht mis ik iets van het grotere geheel van packages ... Maar ik wil het duidelijk hebben, en kunnen neerpennen voor leken ...

ElsLommelen commented 2 years ago

Zodra de PR gemerged is, staat die handleiding op de website van het package. Is dit niet voldoende? Ik vrees dat met een downloadbare pdf het gevaar bestaat dat gebruikers die eenmalig gaan downloaden en er niet aan gaan denken om een nieuwe te downloaden als ze een update van het package installeren, waardoor ze doordenduur met sterk verouderde documentatie aan 't werken zijn. (Op de website heb je wel telkens de nieuwste versie staan, wat ook niet noodzakelijk de versie is waar ze mee aan 't werken zijn, maar als het dan niet werkt als verwacht, kan je dit simpelweg oplossen door hun een update te laten installeren. ;-) )

Trouwens, is je workflow specifiek voor dhcurve? In dat geval is het mss handig om deze ook aan het package toe te voegen, zodat ze die op dezelfde website kunnen raadplegen? (Als je vanalles zou willen toevoegen, dan mss wel best de huidige PR eerst goedkeuren en mij laten mergen, dan kunnen we met je nieuwe PR meteen even testen of de machinerie werkt.)

Intussen verschijnt ook je 2de commentaar: zie PR voor uitleg over hoe je de website nu kan bekijken. Zodra de PR gemerged is en deze website online staat, zal er zowel hier in github als de tutorials website een link komen naar die website. (Dat tekstje voor tutorials heb ik al geschreven, dat mag je goedkeuren zodra deze PR gemerged is.) Maar waarschijnlijk ga je ingeval van dhcurve de link liefst ook binnen ANB op een of andere manier willen verspreiden (dat gaat voor beginners gemakkelijker in gebruik zijn dan als naar github zelf verwijst)?

Meer technisch: die website zou bij het pushen van code naar de master (dus na mergen van een PR) automatisch gebouwd moeten worden en opgeslagen in een extra branch gh-pages (dus lokaal bouwen en de docs folder uploaden is niet nodig, al moet je hem uiteraard nu wel lokaal bouwen om hem te kunnen bekijken), en daarna kan ik in de settings van github aangeven dat die website uit gh-pages online moet komen. De machinerie zou in orde moeten zijn, maar dit in de praktijk testen (en zien of het effectief werkt) kan pas als ik de PR merge... (Dit is trouwens een van de redenen dat ik deze PR zelf moet mergen: om die machinerie naar de master te mogen pushen, moet je admin zijn. Er is trouwens een reële kans dat er toch nog wat misloopt en ik hier en daar nog wat moet aanpassen in die machinerie, want ik heb dat script geschreven zonder dat het al getest is, want het runt enkel bij die merge.)

Je laat maar weten hoe je het wil aanpakken, maar een piste zou kunnen zijn dat je even die laatste aanpassingen van de website bekijkt (ik had enkel nog wat aanpassingen aan kleur en layout gemaakt die je nog niet bekeken had, geloof ik), en dat ik de PR dan alvast merge? Dan kan jij daarna de website en het package bekijken en testen zoals het is, wat mss ook gemakkelijker is om je workflow uit te schrijven (en bv. hierin te verwijzen naar de website zelf voor hetgeen daar al genoteerd staat). Je kan daarna altijd nog om aanpassingen vragen, of evt. die workflow toevoegen in het package zodat ze op de website komt, dan maken we daarvoor gewoon een nieuwe versie van het package en vullen we onder 'NEWS' aan wat er aangepast is in deze nieuwe versie.

leymanan commented 2 years ago

maar een piste zou kunnen zijn dat je even die laatste aanpassingen van de website bekijkt (ik had enkel nog wat aanpassingen aan kleur en layout gemaakt die je nog niet bekeken had, geloof ik), en dat ik de PR dan alvast merge? Dan kan jij daarna de website en het package bekijken en testen zoals het is, wat mss ook gemakkelijker is om je workflow uit te schrijven (en bv. hierin te verwijzen naar de website zelf voor hetgeen daar al genoteerd staat). Je kan daarna altijd nog om aanpassingen vragen, of evt. die workflow toevoegen in het package zodat ze op de website komt, dan maken we daarvoor gewoon een nieuwe versie van het package en vullen we onder 'NEWS' aan wat er aangepast is in deze nieuwe versie.

Je voorgesteld piste lijkt me OK! Bedankt! Ik kijk nu eens naar kleur en layout.

leymanan commented 2 years ago

https://rdrr.io/github/inbo/dhcurve/

Is dat de website van het package?

ElsLommelen commented 2 years ago

Nee, je gaat die lokaal moeten bouwen door de laatste commit van die branch binnen te halen, en dan zie [hier](https://github.com/inbo/dhcurve/pull/44#:~:text=Lokaal%20te%20bekijken%20met%20pkgdown%3A%3Abuild_site()). Pas na mergen van de PR kan ik die online zetten.

leymanan commented 2 years ago

Of bedoel je de kleuren van Handleiding.html? Dat ziet er goed uit! Alleen denk ik dat het overzichtelijker zou zijn met genummerde headings?

leymanan commented 2 years ago

Nee, je gaat die lokaal moeten bouwen door de laatste commit van die branch binnen te halen, en dan zie [hier](https://github.com/inbo/dhcurve/pull/44#:~:text=Lokaal%20te%20bekijken%20met%20pkgdown%3A%3Abuild_site()). Pas na mergen van de PR kan ik die online zetten.

Is gelukt, ook handig dat je me nog eens naar die comment gestuurd hebt. Ik heb net de css gevraagd aan iemand van ANB (is nog tot morgen in verlof...). En als ze dat niet hebben, de RGB-codes.

ElsLommelen commented 2 years ago

Ivm die genummerde headings: Euh, blijkbaar zijn genummerde headings (of een extra level onder Contents) minder eenvoudig dan het lijkt: in de Rmd zelf staat al aangegeven dat de headings genummerd moeten zijn, maar pkgdown houdt hier geen rekening mee bij het bouwen van de website. Dus om dit te kunnen doen, moeten we de stijl van pkgdown overrulen (wat we ook gedaan hebben voor die groene tinten), maar dan is de vraag: gaan we alles nummeren, ook de titeltjes onder NEWS en Funtions en Contributing? Hier lijkt het me overbodig en mss zelfs storend, maar de handleiding wel nummeren en de rest niet, maakt het allemaal wat complexer: normaal schrijf je een layoutfile (css) die op de hele website toegepast wordt, en om een afwijkende layout toe te passen op een deel van een website, moet je in de tekst aangepaste tags gaan maken (dus dan gaan we expliciet html-tags in de Rmd moeten schrijven i.p.v. de titeltjes in markup-language), waardoor het dan weer niet meer mogelijk gaat zijn om het vignet opnieuw als pdf te renderen als we dat ooit nog zouden willen doen.

Ivm die css: Is eigenlijk niet meer nodig, ik heb destijds eens in de stijlgids van de Vlaamse overheid geneusd en daar al een en ander gevonden i.v.m. jullie stijl (RGB-code van dat groen, de andere kleur heb ik zelf verzonnen omdat jullie volgens die stijlgids geen lichte kleuren in jullie pallet hebben), en ook de website en twitter-account heb ik toen ergens gevonden. Maar goed, als je hem toch krijgt, en er zit iets in de ANB-website wat je graag wil dat ik overneem (bepaalde kleur of logo of...), laat gerust weten. (Ik zou sowieso wel deels de opbouw van de website van pkgdown behouden, bv. de titeltjes van de onderdelen bovenaan, en die kolom rechts,... kwestie om het ook wat uniform te houden met andere packages, da's handig voor R-gebruikers die ervaring hebben met info zoeken op die websites.) Trouwens, voor extra inspiratie: ondertussen is de INBO-stijl voor die package-websites ook wat aangepast, met naast het fuchsia ook de steunkleur blauw (zie voorbeeld). Enkele kleuren aanpassen is niet zo moeilijk, de hele layout overhoop gooien doe ik liever niet. ;-)

leymanan commented 2 years ago

Ivm die genummerde headings: Euh, blijkbaar zijn genummerde headings (of een extra level onder Contents) minder eenvoudig dan het lijkt: in de Rmd zelf staat al aangegeven dat de headings genummerd moeten zijn, maar pkgdown houdt hier geen rekening mee bij het bouwen van de website. Dus om dit te kunnen doen, moeten we de stijl van pkgdown overrulen (wat we ook gedaan hebben voor die groene tinten), maar dan is de vraag: gaan we alles nummeren, ook de titeltjes onder NEWS en Funtions en Contributing? Hier lijkt het me overbodig en mss zelfs storend, maar de handleiding wel nummeren en de rest niet, maakt het allemaal wat complexer: normaal schrijf je een layoutfile (css) die op de hele website toegepast wordt, en om een afwijkende layout toe te passen op een deel van een website, moet je in de tekst aangepaste tags gaan maken (dus dan gaan we expliciet html-tags in de Rmd moeten schrijven i.p.v. de titeltjes in markup-language), waardoor het dan weer niet meer mogelijk gaat zijn om het vignet opnieuw als pdf te renderen als we dat ooit nog zouden willen doen.

Als dat zo ingewikkeld is, laat het dan maar!

leymanan commented 2 years ago

Ivm die css: Is eigenlijk niet meer nodig, ik heb destijds eens in de stijlgids van de Vlaamse overheid geneusd en daar al een en ander gevonden i.v.m. jullie stijl (RGB-code van dat groen, de andere kleur heb ik zelf verzonnen omdat jullie volgens die stijlgids geen lichte kleuren in jullie pallet hebben), en ook de website en twitter-account heb ik toen ergens gevonden. Maar goed, als je hem toch krijgt, en er zit iets in de ANB-website wat je graag wil dat ik overneem (bepaalde kleur of logo of...), laat gerust weten. (Ik zou sowieso wel deels de opbouw van de website van pkgdown behouden, bv. de titeltjes van de onderdelen bovenaan, en die kolom rechts,... kwestie om het ook wat uniform te houden met andere packages, da's handig voor R-gebruikers die ervaring hebben met info zoeken op die websites.) Trouwens, voor extra inspiratie: ondertussen is de INBO-stijl voor die package-websites ook wat aangepast, met naast het fuchsia ook de steunkleur blauw (zie voorbeeld). Enkele kleuren aanpassen is niet zo moeilijk, de hele layout overhoop gooien doe ik liever niet. ;-)

OK! Ziet er inderdaad al heel goed uit, en ik zag dat je fb en twitter ook al had toegevoegd. Enige is dat ik nergens heel uitdrukkelijk AGENTSCHAP NATUUR & BOS zie staan (cfr website ANB https://www.natuurenbos.be/ : de bovenste band) Het logo is er ook doorzichtig en staat in dezelfde band.

Is het mogelijk om het logo en de vermelding "AGENTSCHAP NATUUR & BOS" in de groene band op te nemen, vóór de fb en twitter? Fb en twitter is voor mij trouwens minder noodzakelijk dan het ergens vermelden van "AGENTSCHAP NATUUR & BOS" (mocht er te weinig plaats zijn voor beide)

leymanan commented 2 years ago

is het veel moeite om eventueel nog een extra niveau toe te voegen, aan het uitklapvenster rechts (dus ook nog "initiatie"/"fit"/ ... en niet enkel "Berekenen van curves")? Dus 3 niveaus uitklappen, ipv 2 ...

ElsLommelen commented 2 years ago

Euh, voor allebei geldt dat ik moet gaan zoeken en puzzelen in de layout, maar het klinkt wel allebei als een haalbaar idee. Dat logo lijkt niet moeilijk, voor dat 3de niveau kan ik de moeilijkheid niet inschatten. Ik ga het in elk geval proberen (een van de komende dagen, nu ben ik iets anders bezig).

leymanan commented 2 years ago

Je moet er ook niet teveel tijd insteken, hé? Als je al snel doorhebt dat het niet zo simpel is, mag je het laten vallen, hoor! Enkel wel ergens een vermelding van Agentschap natuur en bos, dat wel ...

ElsLommelen commented 2 years ago

Dat logo van ANB toevoegen gaat niet zo moeilijk zijn, dat zal sowieso wel lukken.

ElsLommelen commented 2 years ago

@leymanan Euh, nog een oud issue dat open is blijven staan? Er is nog issue #65 dat ik aan 't oplossen ben (logo onder copyright holder kleiner maken), maar ik neem aan dat dit voor de rest in orde is, en dat er niet per se een pdf moet zijn? (Als eerder aangehaald: een pdf heeft als nadeel dat die in een computer opgeslagen wordt en niet bijgewerkt wordt.)

leymanan commented 2 years ago

had daarnet al snel gezegd dat html ook ok is (terug verwijderd). Maar toen bedacht ik dat ik zelf steeds de pdf gebruik als ik iets wil opzoeken ivm de gebruikte methodiek. Een pdf is handiger dan een html vind ik.

Ook als ik de gebruikt methodiek wil delen met externen die het package niet gebruiken. Desnoods is dat dan een éénmalige pdf, met datum erbij ...

leymanan commented 2 years ago

kan zowel een html als een pdf? Zodat dit ook toegankelijk is voor mensen die geen R gebruiken

ElsLommelen commented 2 years ago

Zodat dit ook toegankelijk is voor mensen die geen R gebruiken

Voor mensen die geen R gebruiken of externen kan je evengoed naar die website verwijzen, lijkt mij, maar dan misschien eerder rechtstreeks naar https://inbo.github.io/dhcurve/articles/Handleiding.html dan naar de hoofdsite https://inbo.github.io/dhcurve/index.html zodat ze niet bij die installatie-instructies uitkomen? ;-) Voordeel van een website is in elk geval dat je niet telkens een nieuwe versie moet nasturen als we iets aangepast hebben, en ik weet eigenlijk ook niet of er in de handleiding links staan die in de pdf niet werken? En eerlijk gezegd: om op een scherm te lezen, vind ik een website vaak handiger dan een pdf, omdat die beter aangepast is aan het gebruik op een scherm: tekstblokken zijn beter aangepast aan de schermvorm en er zijn geen (overbodige) pagina-einden die het lezen onderbreken, klikbare inhoudsopgave in de marge die verder uitklapt in het onderdeel waar je aan 't lezen bent, (evenzeer een zoekfunctie),... Dus mss vraag je beter wat ze graag hebben vooraleer je hun een pdf aanbiedt terwijl ze een website mss handiger vinden?

kan zowel een html als een pdf?

Ik heb al wel repo's gezien met bookdown-rapporten, waar dan bij een release (of merge naar de main) een website met links naar html, pdf en epub versie van het rapport verschijnt, maar ik heb diezelfde automatisatie nog niet zien opduiken in combinatie met packages en het gebruik van een pkgdown-website voor de documentatie. Dus ik vrees dat ik voor zo'n automatisatie zelf een routine zal moeten schrijven, en dat gaat me tamelijk wat tijd vragen. Dus ik ga dit issue liefst wel parkeren tot ik eens veel tijd heb, of tot ik ergens eens een gepaste oplossing tegenkom, of tot ik al wat meer ervaring heb met dit soort routines.

Ik hoop dat het ok is voor u om voorlopig de handleiding nog manueel te blijven renderen als je ze nodig hebt? Dit kan door het scriptje RenderHandleiding.R in de inst-folder te runnen. (Ik dacht een van de komende dagen issue #53 nog aan te pakken, dus wacht best even met het maken van een pdf tot de nieuwe versie van het package er is. Idee is om nu op een paar dagen de kleine en belangrijke issues op te lossen, vooral om van de foutmeldingen af te zijn die dit package al een tijdje gaf. Maar ik vrees dat ik dit issue voorlopig aan de kant ga laten liggen, ik neem aan dat jij ook liever hebt dat ik bv. een hogere prioriteit geef aan forrescalc als je klaar bent met je aanpassingen?)