integrate documentation into the codebase
I've heard from @clement_oudot that the project was considering migrating its documentation away from the current wiki.
I agree that it would be an interesting change:
- A commit/MR would now be tightly integrated with the corresponding documentation change
- External contributors would easily be able to contribute to the documentation (through merge requests)
- The build process would generate its own documentation pages (for the manager) on every build instead of crawling the website from time to time.
- The new documentation platform would hopefully have a better version selection system and search engine (no more LLNG 1.4 results!)
In my spare time I have put together a little demo of what the "new" documentation system could look like. The (very early) results can be seen here: https://maxbes.github.io/lemondocs/start.html This is almost zero effort, obtained from crawling the current wiki and using the pandoc conversion tool, with some light regexping to fix the biggest issues.
As you can see, the automated conversion tool took care of a huge amount of tedious work, and it would mostly be a matter of fixing some links and formatting issues. The home page obviously needs a lot of attention, but you'll notice that the "internal" pages only need a quick review.
I have tried a few different documentation systems, and I think that Sphinx is the most promising. It has nice structure management that allows the doc to be organized hierarchically (not visible in my demo). It has lots of nice features (easy internal links, check for validity of external links, a way to mark 'this feature is available since version X'), and it's used by many projects, and allows us to publish docs on ReadTheDocs, where we might get some extra visibility thanks to the global search engine.
However, it has some downsides:
- It works best when used with the "RST" format, checkout the source code in the demo, it looks kinda like markdown, but it's not exactly markdown
- Sphinx can also do markdown, but not as well (no tables, no "info"/"warning" boxes)
- It does not integrate with perl natively, meaning that the internal perl documentation will have to stay on POD/CPAN for now
- It adds a python dependency to the building of the project. But for the demo I only used packages from the Debian archive
If you are interested, I'm willing to put more time into this, and maybe have a finished version for 2.1.
If you guys know of another good documentation tool you'd be more comfortable using, I'm willing to give it a try to see if I can get some results fast. I already tried MKDocs (based on markdown) but the conversion tool didn't work nearly as well, and it generally felt like it's not the right tool for so many pages of documentation.