I like to use Markdown with latex for maths. For a project earlier this year I've used a markdown extension to host it on readthedocs with mathjax support. It was a bit tricky to set up and doesn't feel so robust, but it works. Here's what I did: https://github.com/mkdocs/mkdocs/issues/253#issuecomment-97424632
I've seen some Julia projects that seem to automatically convert docstrings to documentation but I prefer to use the docstrings only for REPL and write out the documentation in markdown. On Monday, 21 December 2015 06:52:59 UTC+1, Jeffrey Sarnoff wrote: > > Whatever you decide, pandoc <http://pandoc.org> should help you automate > translation, and it is strong enough to lean on. I have not used a markup > system with readable raw files and good math support and just enough > flexibility. > > > On Sunday, December 20, 2015 at 1:43:35 PM UTC-5, Tomas Lycken wrote: >> >> Over at Interpolations.jl, we've started thinking about restructuring our >> documentation a little. We basically have (or will have) three levels of >> documentation: usage docs, specifying how to use the library; math docs, >> fleshing out the mathematical background to the algorithms and assumptions >> we've used; and devdocs, which describe implementation details that might >> not be obvious just from reading the code (for one thing, the library is >> quite heavy on metaprogramming). >> >> The usage/api docs are slowly being migrated to docstrings, with the hope >> that the users will actually be able to find it :) >> >> I'm looking for input on what tools, formats, platforms etc have worked >> well for the other two types of documentation in other projects, and in >> what form you, as users or contributors to the library, would prefer >> consuming that documentation. >> >> A stong requirement is that it is editable, and preferrably also quite >> readable, as plaintext. For the math docs, it's also important (obviously) >> that the support for rendering equations, matrices etc is good. >> >> Have you used any tools or platforms previously that solve these problems >> well? Do you have recommendations about which ones to avoid? >> >> All suggestions are welcome! >> >> // T >> >
