Simplify documentation

[dennissiemensma]

Feature

Overwegen om alle documentatie naar Github te verplaatsen, zodat alles op 1 plek staat.

• Voordeel is ook dat er hier issues en discussies (en ook polls) gedaan kunnen worden.
• Verder geen vertalingen meer ondersteund, wat de drempel om docs bij te werken (of uit te breiden) aanzienlijk verlaagt.

Ik heb al kort gekeken wat de gevolgen zijn. Het grootste nadeel is:

• Geen vertalingen meer, maar opzich is Engels als voertaal voor documentatie prima
• Mogelijk geen meerdere versies meer. Niet perse een probleem, maar soms wat het handig om v4-installaties te verwijzen naar een v4-variant van een stukje documentatie.
• Geen zoekmachine index, al kan ik op readthedocs natuurlijk wel verwijzen.
• Staat los van de code, dus handmatig in sync

Wellicht beginnen met een opzet van een deel van de Engelse docs. Kan gewoon naast bestaande docs en ook net zo makkelijk weer geannuleerd worden als het toch niet zo werkbaar blijkt.

[dennissiemensma]

Oh blijkbaar ondersteunt het ook restructured format, wat ik nu gebruik voor readthedocs, maar eigenlijk wil ik daar vanaf. Vind het een vreselijk format.

[dennissiemensma]

Blijkbaar zit er een aparte repo achter: https://github.com/dsmrreader/dsmr-reader.wiki.git

[dennissiemensma]

Ik laat deze zo. Zolang RTD de hosting blijft doen, kan ik ermee leven dat het los staat van Github.

[dennissiemensma]

Ik ga dit toch doen, maar in versimpelde vorm, zonder vetalingen. DSMR-reader app zelf blijft NL/EN, want die wijzigt amper.

De docs doe ik alleen Engels en ook alleen op Guithub, gewoon in Markdown of iets. Binnen het project.

[dennissiemensma]

Het formaat van de sphinx docs is namelijk echt bananen en het vertalen kost me echt teveel tijd.

[dennissiemensma]

Ik verplaats alles naar MD files in een nieuwe root dir. Ook tegen verwarring.

[dennissiemensma]

Het enige nadeel is dat ik er niet maar "1 versie" van kan hebben, door de natuur van Git. Dus ik check die Wiki alsnog wel even, of dat het fixt

[dennissiemensma]

Het is ook alweer bijna twee jaar geleden sinds mn vorige poging, dus wellicht is het weer wat uitgebreid: https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis

[dennissiemensma]

Geen nieuwe features, maar het is wel stukken duidelijker, dus ik geef het een kans

[dennissiemensma]

Ah ik weet het alweer. Geen ondersteuning voor subpagina's. Opzich nog steeds geen ramp, want dat betekent dat ik de docs binnen de repo moet houden, daar kan het wel.

En ik kan dan de wiki gebruiken als placeholder om te wijzen naar de oude en nieuwe docs.

[dennissiemensma]

Oke docs binnen de repo mist autodetectie enzo. Wellicht dan toch maar bij Read the Docs blijven, maar kijken of markdown daar kan:

• https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html

En dan de NL-vertalingen droppen.

[dennissiemensma]

Opzet via markdown werkt prima:

• https://dsmr-reader.readthedocs.io/en/work-in-progress-v6/

Het mist wat mooie dingen, zoals die tips en warnings, maar de eenvoud wint het daarin.

Plus dat ik ook dingen ga weghalen die oud zijn.

[dennissiemensma]

Nu ook betere template gevonden: https://dsmr-reader.readthedocs.io/en/work-in-progress-v6/ Deze pakt de hele breedte, wat een verademing is. Ik heb het niet zo op het standaard RTD-theme, wat het halve scherm niet gebruikt