TelluIoT / ThingML

The ThingML modelling language
https://github.com/TelluIoT/ThingML
Apache License 2.0
101 stars 32 forks source link

Improve the documentation #263

Open fungiboletus opened 5 years ago

fungiboletus commented 5 years ago
brice-morin commented 5 years ago

IMHO, we indeed need a website, acting as the single place to find helpful resources, documentation, getting started. I would suggest gh-pages. The README.md on the repo is just too messy, and I would only have info for developers on the master repo itself, not for users (who should use the website).

For the interactive tutorial, this is a good idea. A cheap version can be made quite easily (I guess), if we have the thingml compilers available somewhere in the cloud, + a way to run the generated code (packed in docker automatically generated from ThingML) on-demand. Well, actually not so cheap, maybe. A more fully-fledged version would need to use Language Server Protocol so as to get coloration, checks, etc. But I am not sure what support we get from XText there...

fungiboletus commented 5 years ago

Running the code on the cloud is a challenge because even though it's isolated in a container, it's still possible to mine whatever-coin-crap on cpu, run spambots, or worse. I would rather compile the code on the cloud using the javascript browser compiler, and execute it on the client's CPU. Or maybe the C compiler with an emscripten step.

For the editor, a web based editor such as monaco with the correct coloration should be fine. The ThingML DSL is not that crazy, if it's not possible to generate syntax coloration and light completion definitions, it's possible to write them by hand. It does look very easy to do.

In my wet dreams (figuratively) a visual state machine to debug would be so nice. The author of the state machine library has an example that I think we could get inspired from.

brice-morin commented 5 years ago

Yes, I agree with you. Generated JS code executed in the local browser is the way to go.

At some point we had a prototopye of grammar for Atom (which had limitations). So no, not impossible to make something similar in a web-IDE. But we should see what we can get for free, first.

As for the visual state machine, that is also a good idea. We have discussed something similar in the ENACT project, but I am not allowed to work on this project :-) @nicolasferry can probably inform you on this matter.

fungiboletus commented 5 years ago

If you find something that generates the grammar, sure. Personally I'm not planning to spend hours trying to find a tool to generate it, learn how to use, and debug it while it's so simple to do it by hand once in a while.

brice-morin commented 5 years ago

The good thing if we manage to have LSP up and running, is that it is a rather standard way, and then we can get a VSCode plugin "for free", for example.

See that for a XText/LSP/Monaco combo

fungiboletus commented 5 years ago

Neat. I would rather use such an editor than Eclipse to be honest.

brice-morin commented 5 years ago

Well, we can indeed expect the same limitations and the same benefits than the normal Eclipse plugin. With hopefully one single fix to implement to solve the problem in Eclipse and in the web editor. Of course, we need the LSP server running somewhere in the cloud, but we also need the ThingML compilers in the cloud... so not a big deal.

fungiboletus commented 5 years ago

Oh so it needs to run some Java/XText things server side ?

brice-morin commented 5 years ago

at least that is what I think, but I do not know much about LSP in practice...