Easier documentation with Doctor Max
Hi everybody,
I have recently created "Doctor Max", a simple tool to try to make Max 6 documentation easier for third-party libraries. We have used it to document the new version of bach (which, by the way, will be out in a couple of days!), but actually it is a more general tool, and maybe some of you might need it for their own libraries/externals/abstractions. We thought that it was worth to be shared.
The working principle is extremely easy: all documentation is done in your code, in a Doxygen-like way. Once you've properly documented your methods, attributes, arguments, etc., you can launch Doctor Max and obtain all the XML documentation files.
If anybody need such tool, you can download it from this page (Mac only, sorry...):http://www.danieleghisi.com/research
In the zip file, there's also an example of how the code should be commented.
Should you use the app, don't hesitate to contact me to report any bug or issue!
Daniele
this stuff rocks!!! my word!!!
This is great, really helpful. Thanks for sharing.
I'm wondering if you (or anyone else, for that matter) have had any luck getting Max to render your package's docs with its fancy, javascript-based page? I've managed this by using [jweb] and browsing directly to a copied version of c74_docs.html (from /Applications/Max 6.1/patches/docs/dynamic/), but haven't been able to figure out how to get Max to natively do it (for instance, in a help patcher, clicking the "?" tab and choosing "Open Reference"--this will render custom refpages via the "old" documentation renderer)...
Hi jdigerness,
As far as I know what you want is not possible in Max 6.1.x; 3rd party documentation is only renderable via the "old" documentation render.
The latest news I had were that Cycling '74 is changing the documentation renderer for Max 7, and it looks like it will be 3rd-party compatible.
Daniele
Daniele,
Is this still helpful for building documentation in Max 7 and beyond, or did they change their rendering system as rumored? I'm about to build an entire syllabus (complete with tutorials, lecture slides, quizzes) for all 3 of my classes and I was hoping to package everything into something very similar to your bach package and your "bach.overview" patch.
However, if there is a better way to create 3rd party documentation/packages in Max 7 I'd love to hear what the major advantages/differences are. I like the simplicity of the new "Max Tour" layout, and the documentation looks great too.
Are there any tutorials out there that show you how to create 3rd party documentation with all the same style elements and "snippet" boxes that give you the copy button at the bottom right to copy little bits of code?
Also, is it possible to create your own Max 7 lessons?
Hi GMix,
honestly I'm still waiting for Max 7 SDK in order to know the right way to document stuff for Max 7. I don't think that'll happen very soon...
Also truth is I'm not using Max 7 yet (it's too unstable on my 10.6.8), and I won't upgrade before mid-summer. On the other hand, I don't mind share DoctorMax code with you, if you know how to improve it add Max7 functionalities...
Daniele
Regarding reference page documentation: yes we have a new renderer in Max 7 -- but the refpage format has not changed at all. Enjoy!
Hi Tim,
thanks for your answer. I think that GMix was also referring to the possibility of having code snippets in reference (this was not possible in Max 6 documentation, afaik), and custom "Max Tour" layout stuff. I know nothing about the availability of such features for third party documentation. That would be great to have code snippets syntax available, to embed patches in the reference pages!
@GMix: The bach.overview patch relies on a personal tag-based system: we build a dictionary from the @tag specifications, and then navigate through it. This system is not included in Doctor Max, however it is a pretty simple code. I can share it with you, should you need it. Write me at my personal address: daniele ghisi at g mail dot com [no spaces].
d