-
Notifications
You must be signed in to change notification settings - Fork 1
/
docs_start.dox
119 lines (96 loc) · 5.28 KB
/
docs_start.dox
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
/***************************************************************************//**
\mainpage Introduction
\anchor intro
\dot "Compile automation and source-based documentation for OpenSCAD designs."
digraph example {
node [shape=Mrecord, fontname=Helvetica, fontsize=10];
a [label="openscad-amu" URL="\ref intro" style="filled"];
b [label="C++ Programs" URL="\ref programs"];
c [label="Makefile Script Library" URL="\ref library"];
d [label="Support Scripts" URL="\ref scripts"];
a->b; a->c; a->d;
}
\enddot
\section intro_what What is it?
The [openscad-amu] has been developed to support the construction
of automated design flows, using [GNU make], and documentation
generation, using [Doxygen], for [OpenSCAD] designs. It provides a
framework that allows for documentation and build-scripts to be
embedded in <i><b>*.scad</b></i> source along side the design. The
openscad-amu is composed of a collection of \ref programs
"programs", a makefile script \ref library "library", and support
\ref scripts "scripts" that work together to automate and document
OpenSCAD designs.
The design documentation is generated using Doxygen and
openscad-amu includes a source-code _preprocessor_ for
<i><b>*.scad</b></i> (and <i><b>*.bash</b></i>). This preprocessor
provides additional Doxygen [special commands] and features useful
for documenting language-based designs. The design automation
build-scripts, embedded in the source-code, are extracted by
openscad-amu and used to construct makefiles that manage the
generation of the design targets.
By utilizing openscad-amu, OpenSCAD design documentation lives
close to to the source code and dependency-based targets generation
scripts are constructed for use in code testing, code documentation
and design implementation. Moreover, with GNU make, targets can be
processed in parallel which drastically reduces compile times for
larger design projects.
\section design_flow_overview Design Flow Overview
See this \ref vehicle.scad "design source" which applies the
openscad-amu design flow methodology to a trivial example library.
It differs from a typical OpenSCAD design library in that it
includes documentation embedded within comment sections, and
<em>auxiliary build scripts</em> that describe how to render
numerous targets for design documentation and implementation.
\dot "Design Flow Overview."
digraph example {
rankdir="LR";
node [fontname=Helvetica fontsize=10];
edge [arrowhead=vee];
a [shape=note label="Annotated\nSource\n(vehicle.scad)" URL="\ref source_annotate"];
b [shape=oval peripheries=2 label="Automated\nDesign\nFlow" URL="\ref design_flow"];
c [shape=component label="Target (1)\n...\nTarget (96)" URL="../../share/examples/build/html/stl/vehicle_test_car_17.stl"];
d [shape=folder label="Design\nLibrary\nDocumentation" URL="../../share/examples/build/html/index.html"];
a->b; b->{c d};
}
\enddot
When this simple example is processed with openscad-amu, over 750
targets <tt>(*.png, *.stl, etc.)</tt> are constructed.
The openscad-amu coordinates the use of several widely-used tools
to automate the production of these design targets to assemble the
design library documentation in multiple output formats
([HTML][html-example]) ([PDF][pdf-example]) from a single source
descriptions.
\section intro_summary Automation and Documentation
The [openscad-amu] enables two complementary but distinct features
that may be used together or independently:
\li (1) Scripted OpenSCAD design compilation and
\li (2) OpenSCAD design documentation generation.
In either case, meta data is added to the design source code
within structured comment blocks. If you are familiar with
[Doxygen], adding documentation to your [OpenSCAD] designs using
openscad-amu is natural and somewhat straight forward. Markup each
of your design files with the [special commands], name each file in
the project makefile, and type \c make to generate your
documentation. You can start from a template created by the \c
setup-amu.bash script, then customize as needed.
The [openscad-amu] uses git for development tracking, and is hosted
on GitHub at the openscad-amu [repository][amu-repository]. The
[OpenSCAD Mechanical Design Library][omdl] uses the openscad-amu
methodology and is hosted at the omdl [repository][omdl-repository].
[GNU General Public License]: https://www.gnu.org/licenses/gpl.html
[GNU make]: https://www.gnu.org/software/make
[openscad-amu]: https://royasutton.github.io/openscad-amu
[amu-repository]: https://github.com/royasutton/openscad-amu
[issue]: https://github.com/royasutton/openscad-amu/issues
[omdl]: https://royasutton.github.io/omdl
[omdl-repository]: https://github.com/royasutton/omdl
[OpenSCAD]: http://www.openscad.org/
[Doxygen]: http://www.doxygen.nl
[special commands]: http://www.doxygen.nl/manual/commands.html
[html-example]: ../../share/examples/build/html/index.html
[pdf-example]: ../../share/examples/build/latex/refman.pdf
*******************************************************************************/
//
// eof
//