Wanted: a clear, systematic tutorial text + examples of progressive complexity

[JdeH]

What Transcrypt is still missing is a good, systematic tutorial text + examples, suitable for novices.

The combination of a new programming language, a compiler with many switches and pragma's, interaction with JavaScript libraries, and having to deal with a webserver, as well as HTML or the DOM on a client can be daunting at first.

Although I've considered approaching O'Reilly Media and writing a tutorial myself, I don't expect to find the time currently, as working on Transcrypt itself takes up much all most all of my spare time.

Writing a good educational text is far from easy, as I know from my experience as a Technical Computer Sciences teacher at the Rotterdam University of Applied Sciences. Still a good tutorial, starting out at an almost trivial level, would substantially lower the threshold for newcomers to Transcrypt.

So if anyone still remembers how difficult it was to write your first lines of code and on top of this likes to teach and can explain clearly in plain English, he/she's invited to give it a try. If you're embarking on this, let me know, to prevent duplication of effort.

Kind regards
Jacques

[pombredanne]

@JdeH @all3fox is working on a port of not-so-trivial Python libraries (boolean.py and license-expression) and while this is not a tutorial of any kind, this effort did and does require quite a few changes in the original Python code. These have been tracked in details in branches and that history could be a decent base material for such a tutorial as it highlights some of the possible gotchas and how to work around them.

[alisianoi]

The branches in question are:

1. The transpile branch of boolean.py
2. The transpile branch of license_expression

Generally, you can just read the first line of my commit messages to pick up the gist of the change. Also, whenever I end up chaning Transcrypt itself, I submit PRs to you. You've recently merged all of them, so we are running very similar Transcrypt's at the moment.

[amirouche]

My experience with pythonium tells me that most if not all early adopters of projects like transcrypt are developers that don't know JavaScript or don't know graphical user interface development.

[amirouche]

So my question is which audience according to you a transcrypt tutorial must target?

[JdeH]

Target audience, in priority order:

1. Developers who know and like Python and want to use it for web development without speed or size penalty or being cut of from the JS lib world.
2. JavaScript developers who have somehow discovered the advantages of Python and want to use it for web dev.
3. Students and educators (possibly in combination with Numscrypt for a (small?) part of them).

[jeremy886]

Hi, I think this project can benefit from Daniele Procida's How documentation works, and how to make it work for your project from PyCon 2017.

@amirouche hits the nail on the head. I am following Transcrypt because I'm trying to stay with Python as much as I can and it's active enough in this niche. (Rapidscript-ng is probably another good candidate with less participants but a significant user VPython ).

For a public school teacher, anything can be run in the browser is a blessing and that's why even our biggest programming training school is running in the browser. Therefore, I can't afford to ignore javascript solutions when I'm really not good at it.

Our documentation is very detailed at the first glance. But it is kind of too daunting and tiresome for novices to churn through (like me) but not detailed enough for problems I need to solve .

If it can be restructured into clear different categories (tutorials, references, etc) and targeted at different levels. This will help a lot. For example, this excerpt is pretty difficult to follow.

You can test your installation as follows (replacing transcrypt by run_transcrypt if you installed manually rather than with pip):

1. Go to directory ../Transcrypt-/transcrypt/development/automated_tests/transcrypt
2. From the command prompt run transcrypt -b -c -da autotest.py. This will compile the autotests into file autotest.js and put it into the javascript subdirectory. Do NOT go to that > directory (there's no need, stay where you went at point 4)
3. From the command prompt run transcrypt -r -c autotest.py. This will run the autotests with CPython creating file autotest.html that refers to the generated autotest.js file
4. Load the autotest.html into your browser, e.g. by clicking on it (tests were done with Chrome). It will load autotest.js, run it and compare the output with what was generated by CPython. It should report no errors

You can compare my tutorials and wikis for my students and they only use these well if I am present to guide them.

I find the "Sample Code" area stands out and it's a brilliant idea. But nobody walked through the code and no advice with the initial setup. It goes very deep(or broad) very quickly. It is probably okay for different audiences but definitely stops more novices to access Transcrypt.

I felt embarrassed but I wanted to admit that I haven't really figured out how to use p5.js in Transcrypt after reading the documentation and people's advice.

I know I'm teaching at a secondary school but I'll argue adults don't necessarily cope better than kids. I'm happy to write down my tutorials if I manage to get things working later. I hope my humble ideas can help Transcrypt flourish.

[JdeH]

I think your tutorials look beautiful!

It is agreed that the docs are daunting for novices.
That's why I feel the need to have a tutorial.

Making something like you did will cost a lot of time.
Unfortunately I can't do this myself in parallel with Transcrypt and my daytime job.

That's why I created this issue.
I can only hope someone picks it up and starts creating something for Trancrypt in the step-by-step style you've shown.

The sample code is indeed hard for beginners as well.
Nice small examples, starting with concepts like classes, inheritance etc. would be good.

Thanks for the extensive feedback.
Kind regards
Jacques

By the way, probably you will already have noticed you can use TS for some coding directly in the browser, making e.g. simple (turtle) graphics programs. But this is not its main niche. It's for regular development really. But it would be nice if newcomers could also use it.

http://www.transcrypt.org/live/turtle_site/turtle_site.html

[amirouche]

I agree with @jeremy886 the current documentation is not good enough. Without diving into the graphics or design, it's hard to dive into transcrypt. I think we agree on that.

In the getting started section the actual command to compile python to javascript is mixed inside the text. Most people don't read, they scan.

This must be the getting started:

$ pip3 install --user transcrypt
$ echo "print('Héllo, world!')" > hello.py
$ transcrypt -b -m hello.py
$ node hello.js
Héllo, world!

This must be at the top of the README file. This could be made simpler and just drop the options flags from transcrypt command (btw there way too much options flags, but that is another debate).

Regarding @jeremy886 particular needs which aims at teaching python to non programmers. It will be vvvery difficult to teach people on a platform that is not stable. FWIW, you should have a look at termbox library (cf. true color support) which allows to create terminal user interfaces. I think it would be the best options to have both some kind of graphics and a good python implementation.

Daniele Procida's How documentation works, and how to make it work for your project from PyCon 2017.

tx for the link

[amirouche]

Target audience, in priority order:

Developers who know and like Python and want to use it for web development without speed or size penalty or being cut of from the JS lib world.

That's what I was thinking about. How do you do call a Javascript function, this is missing from the getting started page.

JavaScript developers who have somehow discovered the advantages of Python and want to use it for web dev.

This is not going to happen or it will be very hard. Nowdays with ES7, you will have an hard time showing how Python is a better language than Javascript even if it is. You can not consider the stdlib as value asset in Python vs Javascript debate. Because the stdlib is targeted at backend development. And Javascript has npmjs, the most successful package repository of all the time. The only thing that I find painful in Javascript is the regex syntax. The thing that is missing from ES6 classes are metaclasses and multiple inheritance, it has no data descriptors. Also CPython's async/await is better and easier to debug. Does transcrypt support all this things?

Students and educators (possibly in combination with Numscrypt for a (small?) part of them).

Let's forget about numscrypt, most (if not all) science stuff is done in Python. Javascript is the browser language nobody wants to use Javascript to do math and CPU intensive stuff. Let's forget about students and educators. Even if it has been, at last, the sweet spot of Python as a language, it wasn't until Python was used massively used in science and in the industry.

[amirouche]

Well I have many other thoughts to share (like how is exception support in transcrypt, because javascript exceptions are very poor).

At last, to my opinion, a framework that use transcrypt must be built that is opinionated about how to do web development (and another one to do games or art) but first the let's just make a damn todomvc app.

[JdeH]

todomvc in Transcrypt? Nice idea! But isn't MV(C) orthogonal to Transcrypt. I mean, model-view can be done in any language. You can use react from TS etc. Or is that what you're suggesting, a react example in TS?

I've made some small modifications to the website to make the first steps easier:

http://www.transcrypt.org/documentation#hello

About your "getting started":
It is simple and clean.
However node.js is not the first thing that comes to my mind when advocating Transcrypt.
Running JS on a server is only useful if you like JS very well!
And in that case you won't be using Transcrypt, I'd expect.

What do you think of the link above, is that a nice, simple entrance to Transcrypt?