A Template for Generating OpenSCAD Design Documentation

thingiverse

Human: A method for documenting OpenSCAD designs using Doxygen was introduced a while back and has since been refined into an automated design flow. This streamlined process is presented here with a template to get you started. This template can be used as a foundation to add documentation to your OpenSCAD designs. Setting Up the Tools The template utilizes the openscad-amu design flow, which includes a script available for download under Thing Files to set up openscad-amu and its prerequisites: bootstrap.bash: A script to set up the design flow tools. bootstrap.conf: The configuration file for the bootstrap script. To install the prerequisites, fetch and compile openscad-amu, install to a local cache directory, and create a project template, download the bootstrap script to a working directory and type: $ chmod +x bootstrap.bash $ ./bootstrap.bash --cache --yes --install --template my_project You can omit the argument --yes if you prefer to confirm the installation of each package individually (help is available: bootstrap.bash --help). If everything goes smoothly, you will end up with two new directories: cache and my_project. The source will have been compiled and installed to cache, and a template with a project makefile will have been copied to the directory my_project. Using the Template The template consists of: + Makefile: A design flow project makefile. + Doxyfile: A Doxygen configuration file. + (Source): Two example OpenSCAD source files design.scad: A design file. library.scad: A library file. To build the example design project in the my_project directory, type: $ cd my_project $ make install $ make install Yes, you read that right - Type make install twice! This is only required on the installation of the very first project to initialize the table of contents data used to index the installed libraries. This make directive causes the design flow to: * Extract target build scripts from the design.scad and library.scad source files. * Construct and run several makefiles that build the project targets (can be anything that OpenSCAD can render). * Compose the project documentation in several output formats. * Install the *.scad library files to the OpenSCAD user library directory. * Install the project documentation to a central documentation repository. * And, add the project documentation to the table of contents. Releasing and Installing The tools are being developed on Linux and are regularly tested on Cygwin. Pull-requests and issue reports are welcome. I am interested in supporting Mac OS, however, I currently lack a suitable development environment. Cygwin Notes Prior to using bootstrap.bash, be sure to install both (1) Devel/git and (2) Web/wget using the Cygwin setup program. A few years ago, I made a quick attempt to compile a native OpenSCAD binary under Cygwin, but ran into several road blocks. If you have ported OpenSCAD to compile natively under Cygwin, please report. As a fall-back, an OpenSCAD Windows binary is supported if it can be found in the shell search path. However, the full path to the installation directory must not contain any spaces! Either: (1) install OpenSCAD to a path that does not contain spaces or (2) create a executable script and place it in a path that does not contain spaces which will invoke OpenSCAD. For example: #!/bin/bash /cygdrive/c/Program Files/OpenSCAD/openscad $* The easiest solution is to grab a recent snapshot in *.zip format from OpenSCAD snapshots and unzip to a path that does not contain spaces. Then add this path to your shell search path variable: PATH=${PATH}:/cygdrive/c//openscad-20XX.XX.XX As expected, the native Windows OpenSCAD binary does not set POSIX file permissions when creating output files.