Message Boards Message Boards


Simplifying (Making) Mathematica Documentation

Posted 6 months ago
2 Replies
13 Total Likes

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.

enter image description here

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:

enter image description here

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:

enter image description here

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):

enter image description here

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:

enter image description here

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:

enter image description here

2 Replies

Excellent! Hovering over the "thumbs up" icon shows "Rate this as good." Too bad there isn't a bigger thumb.

enter image description here - Congratulations! This post is now a Staff Pick as distinguished by a badge on your profile! Thank you, keep it coming, and consider contributing your work to the The Notebook Archive!

Reply to this discussion
Community posts can be styled and formatted using the Markdown syntax.
Reply Preview
or Discard

Group Abstract Group Abstract