Hey guys,
I’ve just started a tool in python that automatically generates the documentation of a maxscript code, according to the comments found in the source.
It’s kind of a mix between javadoc and python documentation.
The “docStrings” are all the multiline comments that start with / and finish with /
The only elements that are documented are struct and function.
A docstring is always associated with the previously found struct|function.
There can be (there must be !) a starting docString at the beginning of the file, which will describe the script.
The tool is written using Python/Pygments, and a customized RegexLexer.
There are some improvements I’m currently working on before publishing :
[ul]
[li]List function parameters
[/li][li]Specify when a function belongs to a struct
[/li][li]Process @keywords in docStrings
[/li][li]Use reST class to improve docStrings display
[/li][/ul]
Here’s an example of what I have for now :
Sample .ms file
Generated Documentation
Let’s be clear. It’s clearly not intended to handle projects as big as what Doxygen or Sphinx would be able to. It’s a quick’n’dirty hack specifically developed for maxscript.
I mean : if you ever reach that kind of complexity in a project, I really hope you’re not using maxscript anymore !
Now, do you people have some particular wishes in the html output ?
This looks great,
I’m also a fan of commenting and in-line documenting but never had the balls to create something like this.
One question: why not develop this in dotnet and maxscript? That way you could generate the docs directly from within maxscript. I’ve got an mzp-builder for instance which builds my script. Automatically adding the docs would be a great feature.
Anyway, a feature for the docs would be maybe adding hyperlinks to the code itself. That way you can read the docs, but also check out the code without opening 3dsMax.
Also outputting the docs to a pdf with hyperlinks.
If you have a default value for a parameter this could be added to the docs, also if you describe your parameters (bool, int, etc…) this could be added.
Great job already!
I was more comfortable with python, and found all the necessary libraries to use (check http://pygments.org/ ). It’s heavily based on regular expressions, I never used them on dotnet, and there’s no such thing in mxs.
The main goal was to keep it simple : using Pygments’ RegexLexer class (and adjusting it to maxscript syntax), I was able to write the tool in a few lines, no need to reinvent the wheel.
The link to the source code is a nice idea, I’ll add it.
I’m currently working on the function parameters parsing, the default parameter values and url’s generation are planned features.
Update.
- I have the parameters and their optional default value.
- The link to the source code is here too.
- I have to define the workflow behind this (where to run the code, where to output, how to use it : command line, GUI)
Regarding the organization of the document, this is the maximum I can get with no grammar and just a lexical analysis.
In fact, I’m using Pygments RegexLexer class, I can’t make anything more than put some colors and styles, constrained to follow the source code order. And it is exactly what Pygments was created for : syntax coloration !
I’ve realized that when I tried to make things like detecting when a function was declared in a structure (myStruct::myfunction). To make it simple : with no grammar, you can’t.
Nice,
if you also make a commandline tool out of it, it could be used by calling it from maxscript. That would be really handy. No idea if that’s a lot of work though.
I think that creating documentation like this is a big step forward.
I didnt touch regex in dotnet until I learned python. The re module is awesome. I’ve changed how I do string parsing in max now as a result of it. However, as it is regex you can apply the same principles as python to the “System.Text.RegularExpressions.Regex” class in MXS. They’re so useful I keep meaning to write a blog post about how to use them in Max.
However, I’d keep it python and allow it to be called from commandline as klaas says. It doesn’t make much difference for something like this.
great work!
Hi Pete,
I’d be very interested in such an article! To me, regex looks like youngsters sending text-messages.
Regex is awesome and I use it quite a lot, but I don’t understand how people remember the syntax, it’s soo abstract. I know some basic stuff from the top of my head, but above that I use regex coach or something similar.
-Johan
I would say it’s mostly a question of practice.
The main problem in my opinion is when the regexp syntax is not the same between languages.
If I remember correctly, you can find differences between linux shell, perl, etc…
Ha ha, or the sound you make when trapping your nuts in a door. $%^^|*^YArg!
The main problem in my opinion is when the regexp syntax is not the same between languages.
Yes, this is true – I guess there is a little bit of experimentation needed with these things. However it’s not been a big stretch between python and c#.
And I think it’s right that you don’t remember regex syntax Johan, because once you do you know that you’ve gone too far and there’s no way back…