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.
Git Repository: https://github.com/revarbat/openscad_runner <https://github.com/revarbat/openscad_runner>
Documentation: https://github.com/revarbat/openscad_runner/blob/main/README.rst <https://github.com/revarbat/openscad_runner/blob/main/README.rst>
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.
Git Repository: https://github.com/revarbat/openscad_docsgen <https://github.com/revarbat/openscad_docsgen>
Documentation: https://github.com/revarbat/openscad_docsgen/blob/main/README.rst <https://github.com/revarbat/openscad_docsgen/blob/main/README.rst>
More Docs: https://github.com/revarbat/openscad_docsgen/blob/main/WRITING_DOCS.md <https://github.com/revarbat/openscad_docsgen/blob/main/WRITING_DOCS.md>
Install via Pip: `pip3 install openscad-docsgen`
- Revar
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 revarbat@gmail.com
To: OpenSCAD general discussion discuss@lists.openscad.org
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.
Git Repository: https://github.com/revarbat/openscad_runner Documentation: https://github.com/revarbat/openscad_runner/blob/main/README.rst 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.
Git Repository: https://github.com/revarbat/openscad_docsgen Documentation: https://github.com/revarbat/openscad_docsgen/blob/main/README.rst More Docs: https://github.com/revarbat/openscad_docsgen/blob/main/WRITING_DOCS.md Install via Pip: pip3 install openscad-docsgen
- Revar
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
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: http://forum.openscad.org/
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.
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: http://forum.openscad.org/
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