Compile-Scripting and Documentation-Generatation for OpenSCAD Designs…
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.
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
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.
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
You can also start from a template created by the
script, then customize as needed as described in the evaluation
section of the repository home page.
See the GitHub source repository for instructions on evaluating and installing.
This design took approximately 48 hours from concept to assembly and documentation using omdl and openscad-amu. It demonstrates the automated design flow. One can change a design parameter, then type
make allto recompile effected parts. In this design, parts are engraved with a version and part identifier using a simple database scheme available in omdl.
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.