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 >
