Wiki docs generation from source comments

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

Wiki docs generation from source comments

RevarBat
I’ve rewritten my BOSL2 documentation generation system to be independant Python packages.

First is the openscad-runner package, which can be called from other python scripts to run .scad scripts with the OpenSCAD app to generate images or STLs, or other files.

    Install via Pip:  `pip3 install openscad-runner`

Second is the openscad-docsgen package, which can read OpenSCAD .scad source scripts to find specially formatted comments to use to generate markdown documentation, including images generated from OpenSCAD example scripts.  This provides a `openscad-docsgen` command that you can run on the command-line.

    Install via Pip:  `pip3 install openscad-docsgen`


- Revar


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

Re: Wiki docs generation from source comments

OpenSCAD mailing list-2
This looks very cool, and is evocative of Literate Programming:

http://www.literateprogramming.com/

I just wish I could work out a way to write out arbitrary text files directly when running OpenSCAD.

William



-----Original Message-----
From: Revar Desmera <[hidden email]>
To: OpenSCAD general discussion <[hidden email]>
Sent: Sat, Feb 20, 2021 4:25 am
Subject: [OpenSCAD] Wiki docs generation from source comments

I’ve rewritten my BOSL2 documentation generation system to be independant Python packages.

First is the openscad-runner package, which can be called from other python scripts to run .scad scripts with the OpenSCAD app to generate images or STLs, or other files.

    Install via Pip:  `pip3 install openscad-runner`

Second is the openscad-docsgen package, which can read OpenSCAD .scad source scripts to find specially formatted comments to use to generate markdown documentation, including images generated from OpenSCAD example scripts.  This provides a `openscad-docsgen` command that you can run on the command-line.

    Install via Pip:  `pip3 install openscad-docsgen`


- Revar

_______________________________________________
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
|

Re: Wiki docs generation from source comments

Troberg
OpenSCAD mailing list-2 wrote
I just wish I could work out a way to write out arbitrary text files directly when running OpenSCAD.
Yep, that would put OpenSCAD as a linked part of the tool chain, saving lots of manual work.


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
Reply | Threaded
Open this post in threaded view
|

Re: Wiki docs generation from source comments

JordanBrown
On 2/23/2021 6:11 AM, Troberg wrote:
OpenSCAD mailing list-2 wrote
I just wish I could work out a way to write out arbitrary text files directly when running OpenSCAD.
Yep, that would put OpenSCAD as a linked part of the tool chain, saving lots of manual work.

Do you feel the need for the OpenSCAD program to specify the name of a file to be written?  That would be worrisome; it would make it much more possible for an OpenSCAD program to be used to attack the system it's running on.  (But maybe file operations could be disabled by default.)

Or do you just need OpenSCAD-generated data to end up in a file?  That can be done fairly straightforwardly by wrapping OpenSCAD invocations in a shell script or equivalent, and filtering the output.  It could and probably should be easier, but it's not awful today.


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

Re: Wiki docs generation from source comments

Troberg
JordanBrown wrote
Do you feel the need for the OpenSCAD program to specify the name of a
file to be written?  That would be worrisome; it would make it much more
possible for an OpenSCAD program to be used to attack the system it's
running on.  (But maybe file operations could be disabled by default.)
Name yes, directory no. I'm perfectly fine with the file ending up in a predefined location (say, the same directory as the .SCAD file). Even better, allow it to be saved to the same dir as the .SCAD file and any sub directories to that.

I'd prefer not to have to filter the output, as that would require me to write a small program for that before the file is handed on down the toolchain.

If we limited output dir, that would also be a nice way to have export() in code, without having security risks. Basically, just a simple built-in module which writes children() to the specified file (this is part of the reason I want to specify file names, if we look at the long plan), then returns children() for the next call in the stack. Example:

export("engravedpart.svg")
difference(){
    export("blankpart.svg")
    mypart();

    engravepattern();
}


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
Reply | Threaded
Open this post in threaded view
|

Re: Wiki docs generation from source comments

OpenSCAD mailing list-2
Would limiting allowed extension to a small subset of "safe" options help on the security aspect?

I'd like to see .log, .txt, and .nc (or .gcode).

William

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org