[Closed] Maxscript Documentation Generator

Could you give me an idea where regex is invaluable for you in a maxscript (or somewhere else)?

ok Klass,

Here is an example of something I would use regex for. I want everyone to use the same structure for naming maxfiles in a pipeline. In some tools, I want to be able to check that a filename conforms to my save structure or render output structure. So once I have my filepath, I’d like to be able to validate this against a pattern. I could use filterstring and split this up, validating it with matchpattern etc, etc but it would quickly get quite horrible.

let’s imagine that the file naming structure that I want to check for is as follows:

[ul]
Some Indentifying Words Describing the File
Underscore
UPPERCASE artist Initials (but only 2)
Underscore
Version number v or V and 2 digits
[/ul]

So without regex, you are looking at doing filterstring maxfilename “_”, taking the array, checking it has the right number of elements and checking each part for capitals, parsing the version string to integer… you get the idea.

So i’ll make a regex string as follows. One of the problems people sometimes have is they see the entire string, not realising that it is just sections. So lets look at each section first :

"\w*_" - (any word followed by an underscore)

"[A-Z]{2}_" - (Any two letter Uppercase combination followed by an underscore)

"(v|V)[0-9]{2}" - (EITHER a lower or Uppercase letter 'V' followed by TWO Digits)

so with everything all in, that makes :

"\w*_[A-Z]{2}_(v|V)[0-9]{2}"

to use it, I’ll create a dotnetobject in maxscript, passing the regex string into the constructor:

rx = dotnetobject "System.Text.RegularExpressions.Regex" "\w*_[A-Z]{2}_(v|V)[0-9]{2}"

Now there are lots of useful methods available, like .replace and .match, but I just want to check if a filename adheres to a certain pattern, so I will just use isMatch, which takes a string and returns a boolean if it conforms to the regex pattern.

rx = dotnetobject "System.Text.RegularExpressions.Regex" "\w*_[A-Z]{2}_(v|V)[0-9]{2}"
dotNetObject:System.Text.RegularExpressions.Regex

-- this is a legitimate filename
rx.isMatch "JustinBieberVsSlipKnot_LR_v17"
true

-- as is this one, with numbers in the first part
rx.isMatch "JustinBieberVsSlipKnot666_LR_v17"
true

-- underscores are fine
rx.isMatch "JustinBieber_Vs_SlipKnot_LR_v17"
true

-- we don't want lower case artist initials
rx.isMatch "JustinBieberVsSlipKnot_lr_v17"
false

-- we missed the letter v before the version
rx.isMatch "JustinBieberVsSlipKnot_LR_17"
false

-- We want a two digit version string
rx.isMatch "JustinBieber&SlipKnot_LR_v7"
false

So as you can see, we can validate this string against our pipeline configuration in one line. Much cleaner!

Of course there are certainly frailties with this regex pattern, all of which can be avoided with some different pattern configurations but I wanted to just illustrate how to use them without getting into some pointless regex code golf. People seem to like compressing these regex strings into the smallest possible lengths, which is very good for them in showing just how clever they are, but makes it unreadable for the average scripter. There’s a million pages on the internet that can show that.

That’s great Pete. This clarifies it a lot and I think you’ve got your blog post ready as well.

Ok guyz. Here’s a first build.

http://laurentchea.com/dev/MaxscriptDoc/pub/MaxscriptDoc-0.1.zip

You’ll find in the package either an executable file “MaxscriptDoc.exe”, or the sources.

If you want to run it using python, you’ll need Pygments library, and your environment variables correctly set (PATH, PATHEXT)

Usage :
MaxscriptDoc.py -i <inputfile> -o <outputfile>
MaxscriptDoc.exe -i <inputfile> -o <outputfile>

For now, if you want the source to be accessible from the html documentation, the src has to be in the same folder.
It could be an extra option.

As said in the source MaxscriptDoc.py, you can tweak the colors at your convenience in the file mxsdoc.css

I clearly haven’t tried all the possibilities of source code patterns, don’t hesitate to raise the errors here.

Hi Laurent,

that works really nice. I’ve used the .exe with shelllauch. The generated html doesn’t link to the source however, it links to itself.
Just out of curiosity, would it be difficult to adapt this to another notation of the docstrings? I’ve been using the scheme by Johan Boekhoven for quite a while now.

        /*<FUNCTION>
         Description:
             Update the progressbar and display a message.
         Arguments:
             <int/float> theProgress: the progress we're at.
             <int/float> theMax: the maximum value
             <string> theMessage: the message to be displayed, if undefine, the message isn't altered
         Return:
            <string> the message
         </FUNCTION>*/

Anyway, this is really great and will surely help improve my docs. thanks a bunch!

Eventually.

It could be as an option in the command line (it’s the second lexical analysis that would change).

For now I’m focusing on the prospective translation bugs first (the 1st lexical analysis pass)

This work as an html link, it’ll work if you place your source and its doc on an http server.

The little useless update of tonight, a muuuch better css style.

http://laurentchea.com/dev/MaxscriptDoc/output.html

This is great! Congrats.

What about having this integrated with something that listens for files/changes and rebuilds documentation?!

Update available : 0.2

http://laurentchea.com/dev/MaxscriptDoc/output.html
http://laurentchea.com/dev/MaxscriptDoc/pub/MaxscriptDoc-0.2.zip

It should correctly handle subfunctions.
There’s a verbose mode (-v) in case of bug report
It should process plugin definition correctly now (see fooBar in the previous link)
Added some reST like syntax for text style (see the source file in the previous link)