A Template for Generating OpenSCAD Design Documentation

thingiverse

Recently, a path to documenting OpenSCAD designs using Doxygen was presented. Since, this method has been refined into an automated design flow and is presented here with a template. This template can be used as a starting point to add documentation to your OpenSCAD designs. Building the Tools The template uses the openscad-amu design flow. A script is available for download under Thing Files to setup openscad-amu and its prerequisites: bootstrap.bash : script to setup the design flow tools. bootstrap.conf : script configuration file. 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 The argument --yes can be omitted if you prefer to confirm the installation of each package individually (help is available: bootstrap.bash --help). If all goes well, 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 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 in the repository index which may be viewed with a web browser. To view the table of contents: $ firefox ${HOME}/.local/share/OpenSCAD/docs/html/index.html # on Linux $ firefox `cygpath --mydocs`/OpenSCAD/docs/html/index.html # on Cygwin The project makefile coordinates the design compilation flow. All controllable aspects of the flow are set in this file. The details of these configuration options are beyond the scope of this brief introduction. However, attempts have been made to assign descriptive option names. For help and other general information type: $ make help $ make info When you are ready to release your new design and documentation type: $ make release If you release a project that uses this design flow on Thingiverse, please add the tag 'openscad-amu' to help others locate designs with installable documentation. Removing To removed the installed library source and project documentation type: $ make uninstall If you are no longer interested in openscad-amu, you can remove the remaining documentation table of contents index.html files which can be located via the following commands: $ make info-install_prefix_html $ make info-install_prefix_pdf Updates The bootstrap script can be used to fetch and build any branch of the design tools. Multiple tools branches can be installed simultaneously. To download the latest updates, build both the master and develop branch, install to a local cache, and create new project templates: $ bootstrap.bash \ --fetch \ --reconfigure --cache --branch master --install --template-def \ --reconfigure --cache --branch develop --install --template-def Each template will be preconfigured to use the appropriate tool-chain installed in the cache. Design Markup In addition to all of the special commands that are available in Doxygen to markup the OpenSCAD design source files during documentation, openscad-amu provides several new commands/functions that are described in its documentation (some examples are shown in the template example design files). This documentation can be built from the source. To build and view the development branch documentation from a local cache installation: $ ./bootstrap.bash --cache --branch develop --make install-html $ prefix=cache $ version=`(cd cache/openscad-amu && git describe --tags --long --dirty)` $ datadir=${prefix}/local/share/openscad-amu/${version} $ firefox ${datadir}/doc/share/lib/doxygen/html/index.html Replace prefix with the appropriate path for documentation installed to other locations (for example prefix=/usr/local for a typical non-cache installation). Supported System 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 a 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.