Quantcast

Design/work flow automation with documentation generation

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Design/work flow automation with documentation generation

royasutton
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, then customize as needed.

Setup instructions are available at the GitHub source repository.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Design/work flow automation with documentation generation

kintel
Administrator

> On Mar 15, 2017, at 16:21, royasutton <[hidden email]> 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


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Design/work flow automation with documentation generation

royasutton
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Design/work flow automation with documentation generation

royasutton
In reply to this post by kintel
I had a look at runsun’s 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 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. With Doxygen, documentation is done using a markup language 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.



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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Design/work flow automation with documentation generation

nophead
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 <[hidden email]> 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
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Design/work flow automation with documentation generation

royasutton
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
Loading...