Improvements to RO-Crate in Python tutorial

[elichad]

Hello again GTN team, a new job has brought me back :)

Suggesting these changes after following the tutorial myself:

• updated output of get_entities() because ./ Dataset always appears first
• added "name" property to Donald Duck because if you re-export the crate and then continue with the tutorial, the name can appear as None when you print authors in a later section causing confusion
• switched bash commands to Python where possible so it's easier to follow along with the auto-generated notebook
• added explanation of what happens when including the exp/logs dataset in the crate
• added extra CLI commands

One question: The command-line interface section has the student clone an entire repository just to get one folder of test data to run rocrate on. I think it'd be better to host this test data in another repository by itself or as a downloadable zip file, which would simplify the commands needed - I'm happy to update the tutorial accordingly but what's the best approach (or most common in the GTN) to storing the data? Zenodo?

Requesting feedback from @simleo as a maintainer of the rocrate package

[bgruening]

Hello again GTN team, a new job has brought me back :)

I saw you recently on some registration list and was like --- "What can this be, is Eli back?" --- so happy to see you again! :)

[simleo]

Thanks for this update, Eli. I'm a bit taken aback because I never thought of this tutorial to be something "alive" that would need updating, but only a training component written for the 2023 Smorgasbord. If the intent is to keep it in sync with the development of ro-crate-py, there's the matter of avoiding duplication / out-of-sync with the ro-crate-py docs (which are in the repository's README.md), as noted by Eli in this issue. Eli's proposed solution (see the issue linked above) is to keep updating this tutorial and make it the only documentation source. We could do that, though I have a few doubts. E.g. is there a way to see the rendering of a PR such as this one before it's merged? Is the language just GitHub-flavored markdown or something more specialized to the GTN?

[hexylena]

If the intent is to keep it in sync with the development of ro-crate-py,

I think it could be nice? The GTN is a very FAIR training platform, it could be a good way to ensure that it's seen by a number of people.

It's not necessarily that we want to 'take over' your documentation, since you're obviously in the best place to maintain it long term, and this would mean using a different platform and changes going through peer-review which I recognise is an added burden for you @simleo.

I think there are some benefits to having it in the GTN but I can recognise those aren't necessarily aligned with your primary goals of delivering RO-Crate's python library, so, at least from our side, thanks to contributors like @elichad, and potentially others in the future, we can consider also maintaining parallel versions, as an additional place to advertise this really nice library.

Eli's proposed solution (see the issue linked above) is to keep updating this tutorial and make it the only documentation source. We could do that, though I have a few doubts. E.g. is there a way to see the rendering of a PR such as this one before it's merged?

Yes!

• if you just want a basic rendering of markdown there is the github view.
• If you wish to see a fully rendered preview, it's absolutely possible. (this can also be done locally, but many part-time contributors find gitpod easier.)

The fully rendered preview is potentially more important in this case since this tutorial uses one of the advanced GTN features of converting a markdown document directly into a Jupyter notebook which users can use if they're not following along in their own terminal.

Is the language just GitHub-flavored markdown or something more specialized to the GTN?

It is GFM, you can use all the familiar markdown constructs

But there are some jekyll specific, and GTN-specific additions on top.

Jekyll templates out variables such as {{ site.baseurl }} for us, GTN specific additions include features like tip boxes which are written with standard markdown blockquotes plus a css class, plus a GTN specific title <tip-title>..</tip-title> feature.

[hexylena]

I've given you merge permissions @simleo for the future!