Findus23
commented
3 years ago Honestly, I find Sphinx pretty straightforward, so I am not sure what's the improvement when switching to mkdocs. If the improvement is just using Markdown (which I understand is more straightforward than rst) then one could simply use https://www.sphinx-doc.org/en/master/usage/markdown.html.
I have no experience with doxygen, so I can't really say if using it or manually edited files are better, but at least in python I'd prefer doc strings to a separate documentation as they allow to read the documentation with just one "jump to source" instead of having to look up the right part of the website.
Also I think it is okay for the function reference/documentation to be quite separate from the rest of the documentation as they serve a different goal. https://diataxis.fr/ expands nicely on this topic in my opinion and also splits up tutorials (how do I get started/ set up rebound), how-to-guides (the ipython notebooks) and explanation (explaining how rebound works and why it does things the way it does) from each other.
I don't really have a great solution for the c-python split, but I think they are different enough that one can't just write every example in both, so maybe keeping the split as it is now with most examples being in python and the few where it makes sense in C might be good enough.
hannorein
dtamayo
I've been thinking a lot about how to best structure the documentation for this project. At least for the C part, I think the best way is to write the documentation manually rather than relying on some package do extract the documentation from the source files automatically. Using doxygen or a similar package is just either too constraining or too much fiddling around is required to make a simple change. So many times I wished I could just write a simple markdown file.
I'm experimenting with this now on the
mkdocsbranch. From a practical point of view, this means that therebound.hfile will only contain the actual prototype definitions and some sparse comments which are not needed in the public-facing documentation itself. All of the actual documentation is in several markdown files. This means that when changing the API, one has to edit not onlyrebound.hbut also the markdown files to keep them in sync. On the positive side, therebound.hfile should end up a few thousand lines of code shorter!I'm using mkdocs for the rendering of the markdown files with the materials plugin/theme. It's static, looks nice and clean, and can render equations. That's about all we need.
I'm still thinking about the python side of things. I'm probably going to keep the doc strings in the python code itself, but then write a simple script to pull them into various markdown files. For a bigger project sphinx would clearly be the better option, but it again requires too much fiddling around to get a nice looking documentation for a relatively small but somewhat non-standard package such as REBOUND.