Nabble has removed Mailing-list integration.
Posts created here DO NOT GET SENT TO THE MAILING LIST.
Mailing-list emails DO NOT GET POSTED TO THE FORUM.
So basically the Forum is now out of date, we are looking into migrating the history.
For now you should send emails, people will see them, discuss@lists.openscad.org.
openscad documentation genereation/libraries
Locked
 
|
Hello i am searching for a library with joinings, i came across at github a thing called openscad model library, although it looks pretty dead it has a lot of useful stuff in it, and i am thinking about adding my stuff into that... the problem of a hughe collection like that, is that without some automatic documentation generation it is useless (as of now) since you can't find what i t can do, nor how in any efficient way... the guy who started this made an attempt with a system called sphinx... but IMHO it remained a useless exercice ... especially since that sphinx systems seems to use a separate set of files, missing thus half of the available modules, and the result doesn't give any clue about the stuff present, nor where it is, how you call or use it... so i am searching for a system to automaticly extract the documentation out of the scad files, and bevore reinventing the wheel, i prefer to ask if there is allready some thing like that, or if there is one of the usual documentation systems that can handle openscad (or at least parse some doc stuff ? I would love ot use perldoc on it, but didn't manage to get it processing the files... -- ciao Bruno =========================================== http://nohkumado.eu/, http://aikido.nohkumado.eu/, http://aikido.zorn.free.fr _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org |
|
|
On 03.05.20 17:43, Bruno Boettcher wrote:
> so i am searching for a system to automaticly extract the > documentation out of the scad files, and bevore reinventing > the wheel, i prefer to ask if there is allready some thing > like that, or if there is one of the usual documentation > systems that can handle openscad (or at least parse some > doc stuff ? I have not found any existing general-use documentation tool with OpenSCAD support. There's a couple of things people built for their libs, but what I would like to see is direct support in OpenSCAD via syntax like for example python doc strings. If the parsing part is taken care of, it should be much easier to integrate with existing documentation generators. This would need a bit more thinking and work initially, but should be able to produce a much more stable solution in the long run. ciao, Torsten. _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
|
|
|
In reply to this post by bboett
The BOSL2 library has automatic document generation from comments before each
function or module, including both markdown text and OpenSCAD examples. This library is actively being developed. https://github.com/revarbat/BOSL2/wiki -- Sent from: http://forum.openscad.org/ _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org |
|
|
In reply to this post by bboett
On 2020-05-03 17:43, Bruno Boettcher wrote:
> so i am searching for a system to automaticly extract the > documentation out of the scad files, and bevore reinventing the wheel, > i prefer to ask if there is allready some thing like that, or if there > is one of the usual documentation systems that can handle openscad (or > at least parse some doc stuff ? The only practical way to keep such documentation up-to-date is if you can generate it at least partly automatically, so your idea is in my opinion the correct one. A much used documentation-system is doxygen (http://www.doxygen.nl/), with support for several languages. It can generate HTML or other formats. Without support for a particular language such as scad, your choice is between implementing the support yourself, or generating input in a format that doxygen already understands. But at least you need a way to extract the relevant information. That is something I believe OpenSCAD does not have but might benefit from. I had a similar issue with AngelCAD, but the AngelScript language supports extracting detailed information from built-in or application-defined functions/classes, so it is relatively easy to generate doxygen-compatible input based on that and keep it up to date. Doing that my result was https://arnholm.github.io/angelcad-docs/docs/annotated.html Maybe you can modify the OpenSCAD language parser. Carsten Arnholm _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org |
|
I also scrape markdown comments from functions and modules with Python to auto document my library. I just start them with //!, so it it is very easy. I don't think it needs any support from OpenSCAD as lots of other languages don't have it but are still documented, for example C++. I don't have any utilities for joining things though. All my parts have convenient origins and sufficient property functions to get their dimensions and place them plus modules to place things like fasteners relative to them. So I have no problem making assemblies out of them. On Sun, 3 May 2020 at 18:00, <[hidden email]> wrote: On 2020-05-03 17:43, Bruno Boettcher wrote: _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org |
|
|
On 03.05.20 21:30, nop head wrote:
> I don't think it needs any support from OpenSCAD as > lots of other languages don't have it but are still > documented, for example C++. That's true, but having it attached to the parsed data would also allow it to be used from inside the OpenSCAD GUI. Which is not going to happen with random comments where people are using different tools (which does work totally fine for a specific project of cause). ciao, Torsten. _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
|
|
|
In reply to this post by adrianv
hello! could you be more specific? i found that library, but eluded the part about documentation? anyway i gave it a quick hack, in case someone is interested, https://github.com/nohkumado/openscadpod but if bosl does that already not need to continue.... just need to find out how it does it... Am So., 3. Mai 2020 um 18:38 Uhr schrieb adrianv <[hidden email]>: The BOSL2 library has automatic document generation from comments before each -- ciao Bruno =========================================== http://nohkumado.eu/, http://aikido.nohkumado.eu/, http://aikido.zorn.free.fr _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org |
|
|
The link I gave
https://github.com/revarbat/BOSL2/wiki goes to a wiki which documents the BOSL2 library and is entirely auto-generated from the BOSL2 source code using the comments that precede the functions and modules. If you download the source code and look at it you will see the comments. Revar wrote scripts that produce the wiki from the code. I have never run them myself and don't know the details, but I assume they are somewhere in the code base. bboett wrote > hello! > could you be more specific? i found that library, but eluded the part > about > documentation? > > anyway i gave it a quick hack, in case someone is interested, > https://github.com/nohkumado/openscadpod but if bosl does that already not > need to continue.... just need to find out how it does it... > > > > > > Am So., 3. Mai 2020 um 18:38 Uhr schrieb adrianv < > avm4@ > >: > >> The BOSL2 library has automatic document generation from comments before >> each >> function or module, including both markdown text and OpenSCAD examples. >> This library is actively being developed. >> >> https://github.com/revarbat/BOSL2/wiki >> -- Sent from: http://forum.openscad.org/ _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org |
|
|
The BOSL2 docs format is described here: The processing scripts are: -Revar On May 3, 2020, at 1:36 PM, adrianv <[hidden email]> wrote:
_______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org |
Re: openscad documentation genereation/libraries
|
|
In reply to this post by cacb
One of the questions that
needs a firm answer is "what do you want to document?"
If it is just unstructured text from a comment block at the start of each module, that is one thing. If you want "where used" that is another. Do you want to know the meaning of each argument to a module? (parameters vs output) Do you want a list of modules in a file? Do you want a list of global constants and their values? Do you want to know who was the author of the code? What else? General comments about the file? General instructions? Version? It is pretty useless to generate "50 ways to document your model" if the goal is to encourage sharing of models or to have a workable documentation structure that can be community supported. Even if the reporting methods are not available, a spec about how to document a file with its modules would be worthwhile. Once you know what you have to parse, parsing it gets easier. Once you know what the documentation elements MUST be in order to get parsed, one can write module documentation even if it can not be parsed today with some assurance that it will be able to be used in the future. The "correct" way should be clear to everyone so that it is possible to incorporate modules into a model without having to redo the documentation lines to have it automatically incorporated into the project's documentation. JavaDoc has a well defined way to document packages, classes and methods using annotations (@tags) in specially identified comment blocks in code - /** */ as opposed to /* */ which are not included in documentation (implementation details that may change without changing the functionality). No one would think of designing their own schema for Java documentation. https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html There is one Open Source JavaDoc parse that might be useful in creating a JavaDoc-like tool for OpenSCAD. https://github.com/javaparser/javaparser/blob/master/readme.md Might be more. But it might be possible to customize their parser to support the extra annotations required to document a CAD software rather than a Java program. Not familiar with C++ but it looks like JavaDoc https://developer.lsst.io/cpp/api-docs.html Python documentation looks pretty weird compared to Java and C. Perhaps someone else might be better qualified to discuss how it might apply to OpenSCAD. Ron On 2020-05-03 1:00 p.m.,
[hidden email] wrote:
On 2020-05-03 17:43, Bruno Boettcher wrote: -- Ron Wheeler Artifact Software 438-345-3369 [hidden email] _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org |
|
|
In reply to this post by bboett
I add a comment header, like this (sorry for the Swedish):
/*AUTODOC CAT: 2D-geometri DEF: ogival2d(d,dcurve,thickness=0) DESC: Gör en ogival i 2D. PARAM: d Bredd. PARAM: dcurve Diamater på kurvaturen. PARAM: thickness Tjocklek om man gör den ihålig. 0 om den inte ska vara ihålig. PARAM: fn Vidarekoppling av $fn. AUTODOC*/ module ogival2d(d,dcurve,thickness=0,fn=100){ difference(){ intersection(){ xtran(-dcurve/2+d/2) circle(d=dcurve,$fn=fn); xtran(dcurve/2-d/2) circle(d=dcurve,$fn=fn); } if(thickness>0){ intersection(){ xtran(-(dcurve-thickness*2)/2+d/2-thickness) circle(d=dcurve-thickness*2,$fn=fn); xtran((dcurve-thickness*2)/2-d/2+thickness) circle(d=dcurve-thickness*2,$fn=fn); } } translate([-dcurve,-dcurve,0]) square([dcurve*2,dcurve]); } } /*ENDAUTODOC*/ Then, I made a program which reads the file and imports both metadata and actual code. In that program, I can search, read docs, and copy the module definition for easy use. -- Sent from: http://forum.openscad.org/ _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org |
«
Return to OpenSCAD
|
1 view|%1 views
| Free forum by Nabble | Edit this page |