Walkthrough - Documentation

[e-august]

Hi, I found this page in twitter some weeks back. Great thing to use openscad with python. Is there some documentation on the additional functions ?

[Matthieu-LAURENT39]

@gsohler i wouldn't mind writing some docs, but do you know where i could write it?

[gsohler]

Hi Matthieu, this is great because I am very bad at starting documentation. Of course i can fine-tune documentation add details, but starting it is quite a hurdle to me. I don't know the best place to put the documentation, but it need to be a place where many interested people can read and find it. This could be maybe my the "Documentation" tab in my gsohler/openscad repository, maybe my homepage where i advertize python enabled openscad or even completly other options like youtube-videos, but of course this is even more beyond my scope.

Relevant topic which are important to me when documenting is that the aim is to have a 1:1 function name and parameter name match between SCAD and python.(and there is output function and there is os_import function as import keyword is reserved) and each pyopenscad variable can act as a python dictionary to store and retrieve data. i believe this feature is important when crerating libraries from pyopenscad(relative object positioning) i will grant you access to yet another repo ...

[Matthieu-LAURENT39]

I think it would be nice to use markdown for documentation, as it's easily portable later on. In particular, we could use it with MkDocs, so that you could have a copy on your website that you can easily link to. We'd need to store the documentation in another repo though

[gsohler]

Just did a small tutorial on mkdocs and it looks promising. I like that it automatically updates the web page when the source file change. I am just wondering, what's the right theme. Ideally it should be a theme which supports lots of example python codes and many impressive resulting pictures. the theme should not be rather colorful, appealing rather than grayish and boring. Do you have a special recommendation ?

[Matthieu-LAURENT39]

The readthedocs theme is builtin, looks pretty good and is very familiar to python user since it's based on, well, readthedocs

[gsohler]

Can we Go with the readthedocs Theme ? It appears to be a very good choice.

On Saturday, August 5, 2023, Matthieu LAURENT @.***> wrote:

The readthedocs theme is builtin, looks pretty good and is very familiar to python user since it's based on, well, readthedocs

— Reply to this email directly, view it on GitHub https://github.com/gsohler/openscad/issues/1#issuecomment-1666500729, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACCO4MUURDTYP6DMDJOCHZ3XTZAE7ANCNFSM6AAAAAAZGMBO7M . You are receiving this because you were mentioned.Message ID: @.***>

-- Null

[gsohler]

I am wondering if there exists already a repo to store the documention, if we can reuse the openscad_web or its better to have a different one...

[Matthieu-LAURENT39]

It's probably best to reuse the openscad_web repo, so that we can easily host the doc on your website

[gsohler]

My preference ;) I have already added some mkdocs staffolding to the page. watch out for update.php

[Matthieu-LAURENT39]

Nice, i won't be home this week, but i'll add some documentation later (or this week if i have time)

[gsohler]

I will spend vacation in hot spain until september. probably i will not be able to commit code but I am curious, what will happen ...

[gsohler]

seems your focus has changed. again: thank you for all your contributions!

[Matthieu-LAURENT39]

Woops, i actually wrote the documentation a few weeks ago, and i thought i made a PR to ask to merge it, but it turns out i completely forgot that last part :sweat_smile: I just made a PR on the openscad_web repo

[gsohler]

Hi Matthieu,

Haha, this sounds funny. I am glad that I used to have timeouts in my life. Did not look into your additions yet, this is the next step but I am confident it will be more valuable than my 5 sentences of skeleton code 😂 I will let you know ...

On Wed, Sep 6, 2023 at 1:10 AM Matthieu LAURENT @.***> wrote:

Woops, i actually wrote the documentation a few weeks ago, and i thought i made a PR to ask to merge it, but it turns out i completely forgot that last part 😅 I just made a PR on the openscad_web repo

— Reply to this email directly, view it on GitHub https://github.com/gsohler/openscad/issues/1#issuecomment-1707425165, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACCO4MW77N427VIU74SK6NDXY6WPVANCNFSM6AAAAAAZGMBO7M . You are receiving this because you were mentioned.Message ID: @.***>

[gsohler]

Matthieu, your work is online and its a great start! I have already done some tiny edits and additions and still many ideas ... BTW: I added you as a collaborator in openscad_web, so there is no need to create a PR. Just push if you like ....

[e-august]

Great stuff and easy to understand. Today I did my pythonized chess board. I tried the path_extrude from the examples but it fails. Do I miss something ?

[gsohler]

Hi e-august. Right now path_extrude is not in included in the pyton-openscad windows installer as its python-pr3 compiled. I will work on providing a installer with the full function set advertised in my homepage soon