Character TD Reel 2017


Documenting Python Code with Sphinx

Well, it’s been a while.

While silent here, I’ve definitely been busy elsewhere. Follow me on github to see the work I’ve been doing with the Maya API and Py.Qt. Also find me on vimeo for demos of some of the stuff I’ve been working on.

Anyways though, I’ve been meaning to address my WordPress for some time now, so what better way than to document my newly-learned skill of automatically creating documentation from docstrings using Sphinx!

Check out the Docs I created for some of my GitHub projects as an example.


Installing Sphinx is a pretty straightforward task. First of all, make sure Python is in the Path for your command prompt. If you type Python and hit enter and it gives you an error, you know it’s not. If it’s not, make sure to add the file path to the file that contains python.exe into your system’s Path environment variable.

In your favorite command prompt, navigate to the folder you have python installed on (probably something like C:\Users\Benjamin\Python\Scripts). If you open that folder in explorer, you should see an application there called easy_install. In your command prompt, while in the ~\Python\Scripts directory, run: easy_install sphinx

Python will do its thing and lots of new files will be created in the Sphinx directory (can you tell I don’t come from a computer science background yet?). You’re good to go!

Setting up a Sphinx Doc

Setting up a document in Sphinx is pretty easy too. Navigate to a folder in your command prompt and create a new folder (md folderName if you’re using the command prompt). Run the command sphinx-quickstart and it will give you lots of instructions to follow. Most of them are pretty self explanatory, but if you don’t know what some of them do just leave it at its default. You can go back and change them later.

C:\Users\Benjamin\Desktop>md sphinxTutorial

C:\Users\Benjamin\Desktop>cd sphinxTutorial

Welcome to the Sphinx 1.6.6 quickstart utility.

Some notable settings that we can set here that will save us some time later are saying y to the query:

> autodoc: automatically insert docstrings from modules (y/n) [n]: y

This will enable us to generate our documentation into html automatically using special “docstrings”.

Setting Up a Python File for Sphinx Documentation

Besides your regular #comments, docstrings are a special type of string that Sphinx can interpret and convert into professional-looking html. According to, a docstring is “a string literal that occurs as the first statement in a module, function, class, or method definition.”

Here’s an example:

def pointInCone(meshDag, p0):
    “””Determines if/the factor by which a point is inside a polygon cone; i.e. a “Search Cone”

    :param meshDag: The dag path of a polyCone object
    :param p0: A world space vector representing the point to check
    :type meshDag: MDagPath
    :type p0: MVector
    :return: The factor by which the point is in the cone or False if it is not
    :rtype: float, False

# rest of function

It might look like a lot’s going on there, and there is some syntax to be aware of, so let’s break it down.

  • The triple quoted string must go directly after you declare a function. In PyCharm, if you make one it will automatically make the :param: and :return: bits for you.
  • The description for the function goes directly after the triple quote.
  • A blank line separates the description and the parameter descriptions.
  • :param param1: Description of parameter   (How to declare an argument)
  • :type param1: object type   (How to declare that argument’s type)
  • :return: What it returns 
  • :rtype: return type

Pretty self-explanatory, right? You could obviously go way more in depth with these so read up on the Sphinx docstring syntax if you want to learn more.

Besides your docstrings, you also need to make sure your Python file won’t do anything or throw any errors when it runs. Part of this (or at least my workaround) involves surrounding all your imports with Try/except ImportError statements, because many of the maya-specific modules I’m importing aren’t recognized by Sphinx when it goes to parse the file.

Here’s what the end result of the above code gives us in the end:

point in cone result

Setting Things up for Documentation

Okay! Now to actually make our documents. In your Sphinx project folder, find the python file called   and open it up. The first thing we need to do is make sure our python package is in Sphinx’s path, so add the line sys.path.insert(0, os.path.abspath(r”fullPathToPythonPackage”))

  • notice the raw string formatting we used with the r”” in front of the string

Next, if you forgot to do this in the setup, make sure you have “sphinx.ext.autodoc” in the extensions array in the file.

Automating the Documentation

Okay! So now we’re ready to do some documentation!  Create a new rst file called something like code.rst  … In it, give it a heading. This is the name that it will be given in our contents tree later.


Code Docs

Notice the underline under the words. Think of it like an html heading. Different symbols like === or surrounding it on both the top and bottom with symbols will give it different weights in the end.

Finally, we’re going to do what Sphinx was meant to do: autodocs!

*A simple search cone algorithm using vector angles*

.. automodule:: bm_pointInCone


  • In rst format, surrounding text with * with make it italics, and ** will make it bold.
  • After a blank line, we’re saying here that we want Sphinx to run the automodule script on the bm_pointInCone module. Remember when we gave it the full path to its package? That’s why.
  • Using the :members: tag will make documentation for any method in the module that contains docstrings.
  • rst file formats use 3 spaces for tabs instead of 4


Classes are pretty much the same; here’s a basic example:

.. autoclass:: bm_spaceSwitcher_ui.SpaceSwitcherUI

   .. automethod:: __init__


  1. Running autoclass on a class on a module we imported
  2. Making docs for every method that has docstrings on it
  3. Forcing Sphinx to make a doc for the __init__ method using the .. automethod:: function.

Finally, if you want to include a block of code in your rst file (which will eventually become a webpage), you can use:

.. code-block:: python

   import maya.cmds as cmds
   import maya.OpenMayaUI as omui

Notice the blank line after declaring the code block.


Adding Docs to our Webpage

Now that we’ve made our rst file, go to your file. You’ll find code that says

.. toctree::
   :maxdepth: 2
   :caption: Contents:

  • toctree stands for Table of Contents Tree
  • With a max depth higher than one, your contents will expand if it has anything underneath it.

Skip a line and add the name of the rst file we made with all our automodule:: stuff in it.

.. toctree::
   :maxdepth: 2
   :caption: Contents:



Creating the html webpage

It’s as simple as opening up your command prompt again while in the sphinx project directory (C:\Users\Benjamin\Desktop\sphinxTutorial) and running make html 

This will put your web files in the _build folder Sphinx has. Under _build/html you’ll find your index.html file. That’s the “homepage” file. Double click it and see what it looks like 🙂

Don’t like the look? Want it to be mobile-ready? Download and install the readTheDocs theme.


Publishing on GitHub

Okay, so now you want people to actually  be able to see your docs. GitHub has a nice Pages feature that allows you to create webpages for either your entire profile or for a single repo.

If you’re doing it for a single repo:

  1. Create a /docs folder
  2. Put the contents of the  _build/html folder in there.
  3. ***index.html must be in the root of the /docs folder for GitHub to build the site. ***
  4. Create a blank .nojekyll file in the /docs folder so that GitHub won’t ignore the folders that Sphinx made that start with an _
  5. Publish and wait! It sometimes takes around half an hour or so to see the result published. Go for a walk. You’ve been sitting for too long!


If you’re doing it for your page:

  1. Put the contents of the _build/html folder in the root of your project repo. For user pages, GitHub requires the index.html file to be in the root of the repo.
  2. Create a blank .nojekyll file in the root of the repo so that GitHub won’t ignore the folders that Sphinx made that start with an _
  3. Publish and wait! It sometimes takes around half an hour or so to see the result published. Go for a walk. You’ve been sitting for too long!


That’s it! Again, check out my (work in progress) GitHub Page if you want to see what you can do with Sphinx.

Take care!




Making a Picker GUI for Maya with PySide and QtDesigner

The Hopps GUI in Maya 2016.5

The past few weeks have gone into the development of a new picker tool for a character rig I’m finishing up. The UI was designed in the amazing QtDesigner and all the Maya integration was done using PySide (PySide 1 that is).

QT Designer stuff:

The whole design is a QMainWindow widget, and the tabs come from the behavior of two QTabWidget objects.

  1. Do a png playblast of your character in the A or T pose you want them in. You want a nice obvious silhouette to make it easier to place the controls.
  2. Take that png into your ui file in QtDesigner and add it as the pixmap to a QLabel widget. This QLabel should be the backmost object in your design.
  3. In your python code (we’ll get to that later) you’ll have to re-connect the pixmap with the correct file path, but we will do this in QtDesigner so that we have a reference for placing our controls.
  4. Make sure you have “scaledContents” enabled.

Now it was just a matter of adding buttons.

  1. Add a button widget
  2. Give it an original objectName
  3. You can color it if you wish with the styleSheet property.
    1. background-color: rgb(80, 255, 73);\ncolor: rgb(0, 0, 0);
      1. ^^ that’s an example of the style sheet my green buttons shared. The background-color flag controls the color of the button and the color flag controls the color of the text.

The other widgets were pretty straightforward if you’ve ever done any PySide or PyQt coding. Besides QPushButton I used QLineEdit for the Namespace input and QComboBox for the dropdown menu.


Integrating with Maya:

This was one of the hardest parts of the project to figure out. A whole lot of props goes to internet heroes like Brian Kortbus who are kind enough to post information and code relating to QtDesigner and PySide integration. Here’s the problem:

QtDesigner gives you a .ui file which Maya doesn’t know how to deal with. Maya DOES however have integration with PySide, which can take ui files and convert them into objects that Python can deal with. Basically, if you’ve ever hand-coded a UI in PySide, the following code allows you to take your nice ui you made in QtDesigner and make it into something that can be easily integrated with Maya (2016.5 or below):

So for example, if we had a QPushButton object in QtDesigner named addCube_btn, line 56 would then connect its “clicked” slot to the function “someFunction”. It’s really that easy for every other button, it just takes a lot of manual connection. The nice thing is that the names for my controls won’t change much between characters so the UI will be pretty re-usable.

I said earlier we had to do something with the pixmap on our QLabel widget. This is what I did:

self.MainWindowUI.bgdImage_label.setPixmap(QtGui.QPixmap(SCRIPT_LOC + "\\hoppsGuiBody.png"))

If I didn’t do this then the background image wouldn’t show up since the folder that QtDesigner makes the image point to by default isn’t at all what you want. I know there’s a whole resource system and all in QtDesigner but considering this project needed only one pixmap I didn’t really find it necessary to get that deep into learning how to do that. Maybe later.

Connecting Widgets:

Now, there are a few things to note with selecting controls. First of all, you can’t just pass it a control like “L_shoulderFK_CTRL” because you don’t know if the rig was referenced or not. That’s where the Namespace comes in. Instead of just directly selecting my control, I made the buttons call a function that concatenates the defined namespace onto the control. In other words: + ctrl, add=1) where self.namespace is defined as self.MainWindowUI.namespaceTxt.text() in another function.

So that takes care of the selection issue. With that same code, we’re able to do things like select the entire body, reset the selection, key selection…

I think I posted this before but the code I use for a smart reset of an object’s attributes is:

sel =
for obj in sel:
    keyable = cmds.listAttr(obj, keyable=1, unlocked=1, settable=1)
    for attr in keyable:
        default = cmds.attributeQuery(attr, node=obj, listDefault=1)
        if cmds.getAttr(obj + "." + attr, settable=1) != 0:
            cmds.setAttr(obj + "." + attr, default[0])

That’s it for this post. I’ll make another post where I talk about how I tackled the fun problems of pose flipping/mirroring and IK-FK and FK-IK snapping.

A thing to note is that this is all written in PySide1, and Maya 2017 and up uses the newer version PySide2. Unfortunately, just changing the input line doesn’t fix the integration (yes I tried it) but I have seen some posts about the problem that try to fix it. So yes, this rig is for Maya 2016.5.

~ Ben Morgan



Geometry Controls using Nodes

Hi everyone!

This discovery comes directly from a Jason Schleifer video  and I really just wanted to pass it on. It’s a very simple method for creating controls that stick to geometry.

Screenshot (37)
The node layout for this setup

How it works:

  • We get our out mesh from the skin cluster and plug that into a mesh that’s the duplicate of that skinned mesh
  • However, doing that will give us double transforms. That’s where the Transform Geometry node will come in
  • We plug in the World Inverse Matrix to a Transform Geometry node, and get the skinned mesh’s out mesh from our skinned geo’s Shape
  • We then plug in the result of that Transform Geometry node into our new control’s shape.

Overall, it’s a pretty simple process that, so far, seems easy to implement. I made a quick script that does this for you. All you do is select the geometry on the skinned mesh you want to become the control and then give it a child.


RigAssembly Script/UI Test

Hi all!

It’s been a while, but I’ve been very hard at work.

This UI and script is the culmination of a few months of work. It’s a UI for an autoRig script I’ve written.


  • Add any number of arms, legs, etc and connect them to a spine
  • Stretchy ribbon limbs
  • Elbow pinning
  • Smooth twist forearms
  • Noodle arms
  • Hybrid IK/FK ribbon spine
  • Reverse foot setup
  • IK/FK blend
  • FK arm/leg stretching
  • Ability to turn off stretching on limbs


  • Automatic rig coloring
  • Ability to change rig control colors after creation
  • Auto-scaling of rig controls based on character’s height
  • Ability to minimize the amount of ribbons created (for game engine rigs)

Things I’m planning to add:

  • A functionality that will set up your rig’s hierarchy in such a way that unreal will accept it (i.e. all the joints are one hierarchy, the controls are in a totally separate group from the joints, etc. )This should be added very soon.
  • Facial rigging setup. I already have the script written for this, so I just have to implement it into the rig.
  • Ribbon tail module

Simple PySide Maya Scene Cleanup Tool


cleanup ool


Hi all!

Today I’m going to be showing a new tool I wrote using the GUI API PySide for Maya. It’s a little confusing at first, but after a while I enjoyed the level of flexibility and design I was able to get out of it compared to Maya’s simple UI tools. The goal of this project was to learn how different widgets work in PySide and to get comfortable with the process of integrating it within Maya. I learned a lot! I think I’ll be writing all my future GUIs in PySide/QT.

The tool has options for deleting history, non-deformer history, and unused nodes. It also has a re-label tool that has a dropdown menu for different labels to choose from. I chose this method because it allows me to easily predict what the pre/suffixes are that I need to replace out of the string before I append the new suffix on.

The renamer tool is pretty basic but it works. You can even press enter to run its command.

The next project I’d want to do is to figure out how to do some sort of Picker Window-type tool in PySide that’s similar to the AnimSchool picker. After some research, it seems like it’s going to be pretty complex, so I’ll need to start small.




Nurbs Ribbon Script


Hi everyone, hope you’re doing well.

I finished a new script that creates a ribbon using a Nurbs plane. It supports creation with any number of drive and bind joints. Very useful for rigging faces!

Also, now that I have this scripted in an object-oriented way, I can now use ribbons in my auto-rig scripts! What held me back for so long was the follicle creation part, which I found a method to do so here in MEL. The trick is to manually create Follicle nodes and make the connections yourself instead of relying on Mel.Eval for making hair systems (which doesn’t return anything to you).

– Ben


Change Shape Script


Hi everyone, it’s been a while.

I’ve been hard at work on a game project that I’m helping out on and with other college-related activities. Something I find myself doing a lot is I changing rig control shapes, especially since at this point the auto-rig scripts I’m using are ones I wrote months ago that use some clunky shapes.

On a side note, I’ll be re-writing those auto-rig scripts this summer with a whole lot more attributes that I learned from all the rigging I’ve done this year. I’m trying to make my life as easy as possible.

So! Back to the script. This script intelligently gets the world size and position of the shape you want to replace by accessing the its BoundingBox scale and Center. Besides that, I’m doing everything pretty standard. I’m using a polyCube for my cube shape object, so I have to turn off Shading and all the render stats associated with polygons, but it’s pretty basic. The only thing an animator might get annoyed by is just hiding Curves in the viewport won’t hide all the control on the rig. But you can’t have everything (and use the attribute I give you for that, anyways!)

Here’s the script. I’m uploading my scripts on GitHubGist now because they read better and can be downloaded easier if you’d like.

Gist Link