Compile-Scripting and Documentation-Generatation for OpenSCAD Designs…

GPL licensed

It is a framework and tools for automating the compilation of OpenSCAD designs with a pre-processor that allows *.scad to be documented using Doxygen.

Introduction

openscad-amu is being developed to support the construction of automated design flows with Doxygen generated documentation for OpenSCAD language-based mechanical design. It provides a framework that allows documentation and build-scripts to be embedded into *.scad source and incorporates two complementary but distinct features that may be used together or independently:

(1) Scripted Design Compilation, and
(2) Design Documentation Generation.

Both the scripting and documentation is done in the design *.scad source files using auxiliary structured comments. Subsequently, the build-scripts are extracted at compile-time to construct Makefiles that manage design compilation. As for documentation, openscad-amu provides source code prefilters that both extend Doxygen and provide additional special commands with features useful in mechanical design. The design flow automates documentation extraction and formatting for each *.scad source with embedded Doxygen content.

As the design part count increases, so does the benefit of using openscad-amu. The targets in the above diagram represent design components or part variations. Compiling design targets one-by-one is times consuming and error prone and discourages design optimization and/or exploration.

For larger design projects, the increase in benefit is significant as openscad-amu frees designers from mundane dependency and state tracking and provides mechanisms for part compilation and coherent design documentation.

A significant side effect is greatly reduce total project compile time on multi-processor systems via parallel invocations of the single-threaded OpenSCAD compiler. Once compilation flows are described, using the simple scripting scheme, each design target is kept current from source as needed via invocations of make.

For smaller projects, the ability to document a design or library using Doxygen is a convenient way to both maintain and publish the design interface or API.

Getting Started

If you are already familiar with Doxygen, adding basic documentation to your OpenSCAD designs using openscad-amu is straight forward. Simply markup each of your design files with the special commands, name each file in the project makefile, and type make to generate your documentation.

You can also start from a template created by the setup-amu.bash script, then customize as needed as described in the evaluation section of the repository home page.

Setup

See the GitHub source repository for instructions on evaluating and installing.

Example

Contributing

openscad-amu uses git for development tracking, and is hosted on GitHub following the usual practice of forking and submitting pull requests to the source repository.

As it is released under the GNU General Public License, any file you change should bear your copyright notice alongside the original authors’ copyright notices typically located at the top of each file.

Contact and Support

In case you have any questions or would like to make feature requests, you can contact the maintainer of the project or file an issue.