-
Notifications
You must be signed in to change notification settings - Fork 33
Open
Labels
documentationChanges only affect the documentationChanges only affect the documentation
Description
An idea came up within the scope #1193 (comment) by @waxlamp and @melster1010 and IMHO warrants "separate thinking" thus filing a new issue here.
The problem with "more detailed" examples is that they might get outdated even faster than output of --help so it might be important to have them scripted/tested. Here is a few approaches we used/I am aware of
- in https://github.com/ReproNim/containers , a code snippet in https://github.com/ReproNim/containers#a-typical-workflow is executed by CI https://github.com/ReproNim/containers/blob/master/.github/workflows/tests.yaml#L30 at least to gain some smoke testing
- in DataLad we recorded demos which we showed via https://asciinema.org/ . Similarish animated gif in https://github.com/duecredit/duecredit/#to-cite-the-modules-and-methods-you-are-using . In both cases, problem is that those snippets need to be tested! So we got half-way there -- we wrote (and extracted into separate repo: https://github.com/datalad/screencaster) helpers to "play out" "cast scripts". E.g. https://github.com/datalad/screencaster/blob/master/cast2asciinema could be ran on the cast script like those in https://github.com/datalad/datalad/tree/maint/docs/casts . Disclaimer: we haven't done that for years now since handbook.datalad.org folks generalized them I believe within their docs framework.
So I decided to try and running
SCREENCAST_HOME=/tmp/demo ./cast2asciinema ../datalad-maint/docs/casts/seamless_nested_repos.sh output.cast
gave me this cast: https://asciinema.org/a/cWrxRnQJlyQNLHg836qAwRbqA (I believe there was some way to turn them also into gifs)
So, if someone were to do some "catchy" interactive demos
- something like those casts could be used
- they could be re-played out (without asciinema - just https://github.com/datalad/screencaster/blob/master/cast2script and run it) on CI to ensure that code is not breaking them
smth like that.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
documentationChanges only affect the documentationChanges only affect the documentation