A Template for Generating OpenSCAD Design Documentation

Description

Recently, A Path To Documenting Openscad Designs Using Doxygen Was [Presented](Http://Www.Thingiverse.Com/Thing:1714053). 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](Https://Github.Com/Royasutton/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](Http://Www.Stack.Nl/~Dimitri/Doxygen/Manual/Commands.Html) 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](Https://Github.Com/Royasutton/Openscad-Amu/Pulls) And [Issue Reports](Https://Github.Com/Royasutton/Openscad-Amu/Issues) 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](Http://Files.Openscad.Org/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/<Path-To-Unzipped-Files>/Openscad-20Xx.Xx.Xx ``` As Expected, The Native Windows Openscad Binary Does Not Set *Posix* File Permissions When Creating Output Files.

Statistics

Category

Tags