Automatic documentation and project evolution

While designing my Mendel, I found out that I really hate to write documentation. Thankfully, I met Kliment who did such an amazing job on documenting the entire Prusa Mendel build! But this is not a long term solution and I started to realize that changing the documentation with every commit to the repository is boring, so I tend to not to do it. :-/

One solution would be to mark one commit as somewhat stable and optimize the documentation to this point. Unfortunately this would slow down the adoption to the new features by community, so I dumped that idea.

Then I finally realized, that I need to generate it automatically. By that time we just included the makefile into the repository, and I found out that OpenSCAD, my software of choice, has ability to output stuff with an echo statement.
Example of catching output:

OpenSCAD -s test.stl test.scad > test.txt 2>&1

I immediately thought, “This is it! I can easily output what these parts use!!” And possibly create bills of materials (BOM), etc. For example: You have module called M8Nut() which will generate an M8Nut object for cutting out nut traps, etc. With every use it would output “m8nut” to the file ‘test.txt’. After some experimenting I found a few problems:

• It could be used only for OpenSCAD files. I found this really bad ‘bug’, what if we have AOI or DXF stuff in our project?
  
• It would get really ridiculous, when you would be doing lock nuts, washers etc. There would be simply ‘dumb’ objects doing nothing, just outputting themselves to command line. Confusing, right? :-)
  
• It would be much harder to associate parts with each sub-assembly in full project tree.
  Also, you cannot use the OpenSCAD to generate the output, not even do the recursive counting, you still have to use another tool. !!!!!
  

Then I got stuck for few days. Finally, I remembered the JavaDOC comments, even though I hate Java. :-D Basically, I borrowed the style of syntax and comment blocks and started creating ThingDOC! I was writing the documentation for a few weeks in my Prusa Mendel files the way I found to be most natural, then writing of the ThingDOC itself began much later. Basically, I started after all files were already commented. Basic ThingDOC comments looks like this:

/**
* Slides on the x-axis with extruder.
*
* @name X carriage
* @category Printed
* @using 4 m3x10
* @using 4 m3washer
* @using 4 m3nut
* @using 4 bushing
*/

I don’t want to talk about syntax here, there is already a wiki page about it. Let’s talk more about what it can do now and what I will do in the future.

ThingDOC looks for these comments in files with .scad and .tdoc extension. It doens’t matter where you put them. This allows use for non-OpenSCAD things. Now its in stage where it can make a BOM for full project, recursively. For example, when you need 8 M8 nuts for one frame-vertex and mendel uses 6 vertices, it will add 64 M8 nuts to the final bill of materials.
Even this alone is very useful, since you will at least have all the needed parts for the commit of repository you actually have, and you won’t be missing something.
It also generates nice summary of parts with their descriptions.

What does documentation look like from actual files in Prusa Mendel repository.

A more important thing, which is not as obvious is that it has a full tree of parts. This is more valuable then it looks like, since later on we can generate assembly documentation.

As I mentioned in above, my ultimate goal is to make the full assembly files automatically generated, in the quality you can find now on the wiki. I already have a plan how to do it. Of course it can’t be fully automatic, but you will have at least hyperlocal assembly instructions, which would be structured and more easily recognized.

An example of why this is still beneficial even though it seems as same amount of work as now: Imagine that nophead wants to fork my Mendel, if he doesn’t like one part (for example, the carriage) it would have completely different mounting etc. etc. So he forks the repository and does all the changes he wants to do, including documentation changes in the carriage.scad. He changed only one single file, but he’s still able to generate documentation for full printer, and the documentation will make sense!

Hyperlocal documentation for the win!

Every commit will then have its own documentation. I know it sounds like science fiction but I really love this idea.

Project can be more living thing then rapid jumps every few months when new release is published.

Again I can show small example how this in connection with GIT is huge game changer!
Once Original Mendel (as now community calls Sells) was released it became more or less untouchable thing. Only changes I remember in SVN was repairing STLs. At first because the SVN is bad for forking branching and even if someone wants he cant express his ideas there, its not open for everyone. And second, the release was so huge that everyone excepts its final thing. In opposite, in my repository, things are changing on daily basis and community accept these changes fluently!! When I browse flickr and internet I can see how quickly community is using updated files etc. In repo is now many great changes by Spacexula, soon from GregFrost. I try to encourage guys to change and tweak. Prusa Mendel will never have something like ‘stable release’ or ‘version 0.1’, never!

‘You have and idea? Go FORK yourself!!’ And it works!!


Back to assembly instructions. How I want to do it: Since we already have the tree of parts it’s easy to know where to start, from the roots, generating one subassembly after another, going up and up until full documentation is ready. Let me show it by example:

/**
* Printer
*
* @root
* @name RepRap
* @assembly Make sure you have [frame] ready.
* @assembly Second you make the [x-axis].
*/

/**
* Printer base
*
* @name frame
* @using 6 frame-vertex
* @assembly Do the side triangles.
* @assembly Connect triangles into frame.
*/

/**
* x axis
*
* @name x-axis
* @using 1 x-end-motor
* @using 1 x-end-idler
* @assembly Prepare [x-end-motor]
* @assembly Prepare [x-end-idler]
* @assembly Put both together with rods.
*/

So first it will generate the frame assembly instructions, since there are no other subassemblies, it will write it out. Second is the X axis but it has some things which logically must be assembled sooner then the x-axis itself, so x-end-motor part goes first, since its mentioned sooner, then the x-end-idler and so on with other instructions.

If you want to play with it, you can clone Prusa Mendel repository switch to development branch and run

git submodule init; git config -l; git submodule update

for initialization of submodules (ThingDOC is submodule). Then you need to install Python and LaTeX (sorry we love the output, but switching to mediawiki etc should be easy). Last you run shell scrip generate-documentation.sh and you are done!

I’m looking for other developers willing to help me with this. I find myself having less time for this then I would love to have, but I think it’s an even more important thing than the Prusa Mendel itself. Or even if you don’t want to help with development and have some ideas what this meta data could be useful for other than the BOM and Assembly instructions, leave a comment.

• ThingDOC
  
• Prusa Mendel
  
• Example of documentation
  
• Josef Průša
  

Jo