Design/work flow automation with documentation generation
openscad-amu https://royasutton.github.io/openscad-amu is being developed
to support the construction of automated work flows and Doxygen-based
documentation for OpenSCAD designs.
It incorporated two distinct but complementary features that may be used
together or independently: (1) design automation and (2) design
documentation.
If you are already familiar with Doxygen, adding basic documentation to your
OpenSCAD designs using openscad-amu is easy. Simply markup each of your
design files with the special Doxygen commands, reference each file in a
Makefile, and type /make/ to generate your documentation. You can start from
a ready-made template created by the bootstrap
https://github.com/royasutton/openscad-amu#bootstrap , then customize as
needed.
Setup instructions are available at the GitHub source repository
https://github.com/royasutton/openscad-amu .
--
View this message in context: http://forum.openscad.org/Design-work-flow-automation-with-documentation-generation-tp20928.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
On Mar 15, 2017, at 16:21, royasutton roy_sutton@hotmail.com wrote:
openscad-amu https://royasutton.github.io/openscad-amu is being developed
to support the construction of automated work flows and Doxygen-based
documentation for OpenSCAD designs.
Looks cool!
How similar is your idea to runsun’s DocTest project?
https://github.com/runsun/openscad_doctest
-Marius
I am not familiar with the doctest effort, but I will certainly have a look
to check for overlap and/or distinctions. Thanks for the feedback and
reference!
Roy
--
View this message in context: http://forum.openscad.org/Design-work-flow-automation-with-documentation-generation-tp20928p20946.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
I had a look at runsun’s DocTest
https://github.com/runsun/openscad_doctest . DocTest is an OpenSCAD
library for:
(1) documenting a function/module interface.
(2) constructing test modules that validate function behavior.
To document a function, DocTest uses a 5-element list variable (added to the
OpenSCAD deisgn) to describe the functions: name, arguments, return type,
category, and description. The DocTest library can subsequently be
instructed at compile time to converts the list-values into the function
documentation by using a mode variable. The documentation is presented in
the OpenSCAD console.
DocTests also includes a collection of data type identification functions,
list/array processing operations, and proposes a method of writing function
validation/test modules based on input sets and expected results.
@runsun, please correct me if I have misrepresented the project in anyway.
My impression is strictly from reviewing the project README.
openscad-amu https://royasutton.github.io/openscad-amu has two main
goals:
(1) design and/or library-api documentation.
(2) design flow automation.
It is clear that one of the big missing pieces in OpenSCAD design is the
lack of good library documentation and both DocTest and openscad-amu
attempt to address this. The deficit is not a shortage of good libraries,
but rather the lack of good collections of validated and documented
libraries. openscad-amu does not address /validation/ and inasmuch there
is potential for collaboration. openscad-amu does provide a framework
where /any method/ of validation may be completely automated.
openscad-amu takes the approach that documenting *.scad is not all that
different from any other programming language and provides a source code
/preprocessor/ that allows *.scad to work with Doxygen
http://www.stack.nl/~dimitri/doxygen/index.html . With Doxygen,
documentation is done using a markup language
http://www.stack.nl/~dimitri/doxygen/manual/commands.html that is placed
in comments. Doxygen subsequently extracts the comments to produce the
documentation in various output formats (HTML, PDF, and several others).
The openscad-amu preprocessor offers /additional capabilities/ useful in
language-based mechanical design. For example, is easy to create a table of
all generated (stl, png, svg) targets, or tabulate all render times across
any number of input, or post-process the output of one target and use it as
input to the documentation (demonstrations, dimensions, line counts, bom,
etc).
The second focus of openscad-amu is design flow automation. Having a solid
automatic design flow for OpenSCAD opens many possibilities. Towards that
goal, openscad-amu proposes a mechanism to embed auxiliary OpenSCAD and
build scripts into /"scoped"/ comment block of a design (**.scad*).
openscad-amu then extracts these auxiliary scripts automatically at
compile-time to generate dependency-base automated design flow compilations.
http://forum.openscad.org/file/n20984/flow.png
Any feedback on direction, problems, suggestions are welcome. if you want to
create comprehensive documentation or automate your design flows, then you
should have a deeper look.
To see it in action on a debian-based system is fairly painless. Just follow
these bootstrap instruction
https://github.com/royasutton/openscad-amu#bootstrap .
--
View this message in context: http://forum.openscad.org/Design-work-flow-automation-with-documentation-generation-tp20928p20984.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
Sorry, but what is "design flow automation"? I have heard the term before
and Google doesn't seem to know.
On 21 March 2017 at 17:08, royasutton roy_sutton@hotmail.com wrote:
I had a look at runsun’s DocTest
https://github.com/runsun/openscad_doctest . DocTest is an OpenSCAD
library for:
(1) documenting a function/module interface.
(2) constructing test modules that validate function behavior.
To document a function, DocTest uses a 5-element list variable (added to
the
OpenSCAD deisgn) to describe the functions: name, arguments, return type,
category, and description. The DocTest library can subsequently be
instructed at compile time to converts the list-values into the function
documentation by using a mode variable. The documentation is presented in
the OpenSCAD console.
DocTests also includes a collection of data type identification functions,
list/array processing operations, and proposes a method of writing function
validation/test modules based on input sets and expected results.
@runsun, please correct me if I have misrepresented the project in anyway.
My impression is strictly from reviewing the project README.
openscad-amu https://royasutton.github.io/openscad-amu has two main
goals:
(1) design and/or library-api documentation.
(2) design flow automation.
It is clear that one of the big missing pieces in OpenSCAD design is the
lack of good library documentation and both DocTest and openscad-amu
attempt to address this. The deficit is not a shortage of good libraries,
but rather the lack of good collections of validated and documented
libraries. openscad-amu does not address /validation/ and inasmuch there
is potential for collaboration. openscad-amu does provide a framework
where /any method/ of validation may be completely automated.
openscad-amu takes the approach that documenting *.scad is not all that
different from any other programming language and provides a source code
/preprocessor/ that allows *.scad to work with Doxygen
http://www.stack.nl/~dimitri/doxygen/index.html . With Doxygen,
documentation is done using a markup language
http://www.stack.nl/~dimitri/doxygen/manual/commands.html that is
placed
in comments. Doxygen subsequently extracts the comments to produce the
documentation in various output formats (HTML, PDF, and several others).
The openscad-amu preprocessor offers /additional capabilities/ useful in
language-based mechanical design. For example, is easy to create a table of
all generated (stl, png, svg) targets, or tabulate all render times across
any number of input, or post-process the output of one target and use it as
input to the documentation (demonstrations, dimensions, line counts, bom,
etc).
The second focus of openscad-amu is design flow automation. Having a
solid
automatic design flow for OpenSCAD opens many possibilities. Towards that
goal, openscad-amu proposes a mechanism to embed auxiliary OpenSCAD and
build scripts into /"scoped"/ comment block of a design (**.scad*).
openscad-amu then extracts these auxiliary scripts automatically at
compile-time to generate dependency-base automated design flow
compilations.
http://forum.openscad.org/file/n20984/flow.png
Any feedback on direction, problems, suggestions are welcome. if you want
to
create comprehensive documentation or automate your design flows, then you
should have a deeper look.
To see it in action on a debian-based system is fairly painless. Just
follow
these bootstrap instruction
https://github.com/royasutton/openscad-amu#bootstrap .
--
View this message in context: http://forum.openscad.org/
Design-work-flow-automation-with-documentation-generation-
tp20928p20984.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
nophead wrote
Sorry, but what is "design flow automation"? I have heard the term before
and Google doesn't seem to know.
With respect to OpenSCAD, that is a good question and I have no
/authoritative/ definition! But I will give my /option/.
My background is integrated circuit design and in my world we often use
terms like design flow, electronic design flow, design flow automation,
electronic design flow automation, etc..
A design flow is, essentially, the sequence of steps and tools used to
convert a digital design description into a physical implementation. As for
integrated circuits, where designs have very large numbers of interdependent
parts, its best done with the assistance of computers in pre-described
automated steps.
Years ago I worked with a group who did R&D on /silicon compilers/. As a
result, I have a world view that thinks OpenSCAD has the potential to do for
/language-based mechanical design/ (made this term up) what silicon
compilers did for integrated circuit design. Namely: significantly reduce
design times, produce correct-by-construction implementations, and empower,
smaller teams of non-IC geeks to create IC-based solutions, etc.
As for designing mechanical objects, I see that OpenSCAD can plays an
essential part in a process of converting high-level textual design
descriptions into customized physical implementations. /The implementation
process brings together numerous conversion tools and steps which make up
the design flow./
The real power is when the design components can be abstracted at a high
level and the user can plug-in parameters that best suit the parts/standards
he/she have on hand and then reprocess a system-level design description
with minimal interaction to obtain a customized product implementation. An
automated mechanical design flow allows thoughtfully constructed design
descriptions to be used to generate highly customized physical objects that
work with local materials/standards (pipe size, switch type, material
properties, dimensions, limits, etc) or even for the countless differences
in people (prosthetics, teethes, eyewear, custom furniture, etc).
As a concrete example to accompany my babble: One goal on my to-do list is
to create a CNC design that can be assembled anywhere in the word that can
makes use of local materials. For example, we don't all use the size boards,
bars, switches, balls, rails, etc. A good portable design should allow the
users to specify the component properties on-hand and allow an automated
design flow to account for differences throughout the implementation.
Roy
--
View this message in context: http://forum.openscad.org/Design-work-flow-automation-with-documentation-generation-tp20928p20987.html
Sent from the OpenSCAD mailing list archive at Nabble.com.