The Documentation Center is nice. The docs are reasonably complete. Stuff is somewhat searchable. It looks really nice. But if you've ever made your own system for generating these kinds of docs you know it's a lot of work. The notebooks are unnecessarily complicated. There are cutesy little elements here and there that don't really buy us much.
I wanted something cleaner that would be easier to write, more transparent, and, crucially, more distributable. What I came up with was the SimpleDocs package.
I'll write a more extended example soon and once the interface has gelled completely, but I want to show off what it can do for us, entirely automatically. To do so I decided to make documentation for my (admittedly a little bloated) package development package BTools.
The first thing I did was start a new project from the SimpleDocs interface (I'll document that later so it's easy to follow along). The build folder started out much simpler (but I didn't have to do much of anything for it!) but here's what it looks like now:
I'm making two things in tandem, on the one hand I'm making docs that integrate nicely with the documentation center. Here's an example of what I get when searching for WebSiteBuild locally:
It looks a lot like WRI docs (excluding the fact that I only have autogenerated content and the "Details" are hidden), but there are a few key differences, the big two being that it's much, much simpler internally and it's version independent. I package my own stylesheet with the docs, so they can be used cross version without issue and without looking terrible.
All the content in that notebook was generated automatically, though. I didn't write any of it (and there are lots of details and options you don't see here). In fact, I actually generated all of the function docs automatically, and now I can go back and more fully document the big ones at my leisure. There is also a tutorial on how this works in the SimpleDocs docs.
At the same time as I build the docs notebooks I also built out .md files for each docs page. This is nice because these can then be fed into any number of website generators to make nice docs websites. Here's the website I built for BTools that comes automatically from SimpleDocs (again, this will be documented more thoroughly in the coming weeks):
In this there's an index of functions and if I had guides or tutorials yet there'd be an index for both of those as well.
You can also search for keywords which is powered by tipuesearch:
And there is much, much more I could do with this website and things. At the moment I'm really just scraping the very most basic stuff of what I can automatically do without any real effort on my part (except for in development).
Hopefully this has shown that Mathematica docs can be simpler and, once I've finished using this package to document itself, can be simpler to make for anyone. As I said, I'm hoping to get this done and finalized in the next few weeks and once that is through I will write here again (and write a blog post) detailing how you can easily use it for yourself.
In the meantime here's a video of the documentation for BTools being autogenerated:
