openscad documentation genereation/libraries

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

openscad documentation genereation/libraries

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

Re: openscad documentation genereation/libraries

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

Re: openscad documentation genereation/libraries

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

Re: openscad documentation genereation/libraries

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

Re: openscad documentation genereation/libraries

nophead
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:
> 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

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

Re: openscad documentation genereation/libraries

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

Re: openscad documentation genereation/libraries

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


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

Re: openscad documentation genereation/libraries

adrianv
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 &lt;

> avm4@

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

Re: openscad documentation genereation/libraries

RevarBat
The BOSL2 docs format is described here:

The processing scripts are:

-Revar


On May 3, 2020, at 1:36 PM, adrianv <[hidden email]> wrote:

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 &lt;

avm4@

&gt;:

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

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

Re: openscad documentation genereation/libraries

OpenSCAD mailing list-2
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:
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

-- 
Ron Wheeler
Artifact Software
438-345-3369
[hidden email]

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

Re: openscad documentation genereation/libraries

Troberg
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