dead-claudia
commented
1 month ago For the foreseeable future, I don't see us switching to anything else. No need to replace what isn't broken. I will document the current local dev process, though, so it's easier for people to get started.
Docs generators aren't really suitable for us, for a couple big reasons:
- Docs generators focus on methods and functions, which is fantastic for traditional libraries, and some small embedded DSLs can get away with that, but they tend to fall apart for larger embedded DSLs like ours.
- The core API is relatively small, but the amount of detail we go into is exceptionally high. There would be so much documentation in code comments, it'd make the core code itself difficult to follow.
Is there an existing issue for this?
Offending URL
https://mithril.js.org/
Issue description
I already worked on several documentations for open source projects and in helped me to use a software like e.g. https://www.mkdocs.org/ to generate the documentation. A lot of things (e.g. code highlighting, search) is already included or available as plugins.
I don't know in what direction you want to go but at least write in the README how you want to generate the documentation in the future. (How does the automatic process look like etc.