NRE Labs Community

"Antidote" CLI Tool - Pre-Release Testing

Version 0.6.0 is going to be released soon, and one of the big features of this release is the new antidote CLI tool, which is a companion tool for curriculum authors. The idea is that if you want to create a new lesson, this tool should make it a lot easier to get started.

I would like to get some feedback on this tool prior to the 0.6.0 release. As a result, the experience may have some wrinkles, and the only documentation you’ll find is on this post here. If you’re still game, read on.

I have already set up a pipeline where all supported binaries are compiled nightly. In the next section, I’ll include instructions for how to download the tool to your system. The URLs provided point to a location where you can find the latest compiled binaries every day. So during your testing, revisit this section once per day to ensure you have a fresh copy.

In terms of feedback, this is early and wrinkles are expected, so please just take notes during your testing, and when finished, post them as a response to this forum thread. When I have a chance to address the feedback with a PR, I’ll respond with relevant links. You can expect those fixes to be available in the next days binaries, and I’d ask that you try again sometime after that point and let me know if things are headed in the right direction.

Please provide feedback in this thread. Once 0.6.0 is out, feedback is still welcome (as I can make improvements any time), but I may ask you to direct your comments to Github.

Clone the Test Curriculum

I haven’t yet converted the NRE Labs curriculum to be compatible with recent changes, so for this testing, we’ll use the test curriculum for Antidote. Clone this to your machine like so:

The NRE Labs curriculum has been updated to be compatible with the latest changes, so you can clone that curriculum as a starting point:

git clone https://github.com/nre-learning/nrelabs-curriculum.git

You should only need to do this one. Take note of the path to this curriculum - you’ll need to provide it when using the antidote tool.

Installation Instructions

First, select the platform and archive type you wish to download. If your platform is not available below, please let me know. Note that a hashes.txt file is also available if you wish to check the integrity of the downloaded files using a SHA256 hash.

Follow the instructions below for your platform to download the one that is right for you, and extract the archive. Regardless of platform, you’ll get three binaries. For this exercise, ignore antidoted and antictl. The only one you’ll need is antidote. Open your operating system’s terminal program (for Windows please use PowerShell) and run the relevant commands below:

Windows

$ProgressPreference = 'SilentlyContinue'

Invoke-WebRequest https://storage.googleapis.com/antidote-nightly-binaries/antidote-windows-amd64.zip -O antidote.zip

Expand-Archive -Force -LiteralPath 'antidote.zip' -DestinationPath .

.\antidote.exe -h

Linux

curl -o antidote.tar.gz https://storage.googleapis.com/antidote-nightly-binaries/antidote-linux-amd64.tar.gz

tar xvzf antidote.tar.gz

./antidote -h

MacOS

curl -o antidote.tar.gz https://storage.googleapis.com/antidote-nightly-binaries/antidote-darwin-amd64.tar.gz

tar xvzf antidote.tar.gz

./antidote -h

If you see Antidote’s help output, then you’re on the right track. Note also that the compilation date is provided for these binaries, so you can know if you have the latest copy.

Testing Instructions

This tool currently supports the creation of Lessons and Collections via an interactive wizard. You can go through these wizards with the following commands:

Note for windows users to replace antidote with antidote.exe

./antidote lesson create
./antidote collection create

There are links to the documentation throughout the wizard. Note that the docs haven’t been updated to reflect the new format, but many of the concepts like Endpoints and Presentations are still valid, even though the new syntax may be slightly different. So if you’re coming in totally cold, these references are still useful to come up to speed on the concepts, as long as you don’t take it too literally.

Note that at the end of each of these wizards, it will ask you to provide the path to the curriculum. For this, just provide the path to the test curriculum you cloned earlier.

At the moment, the files generated by the previous wizards should be mostly correct, but are not guaranteed to produce working content out of the box. There are some things that the wizard can’t do for you. However, the antidote validate command can be used once you’ve generated content via the previous commands to let you know what’s left to do.

To do this, run:

./antidote validate <curriculum>

where <curriculum> is the path to the curriculum you cloned earlier.

This will produce a bunch of log messages about importing resources in the curriculum. If you created a resource earlier, you’ll probably see some errors with instructions on how to fix. Please make the relevant fixes, either with your shell or with a text editor. Once you’ve seen a message that starts with Successfully imported..., followed by the slug of the lesson(s)/collection(s) you created, without errors, you’ll know you have valid content.

Feedback

Again, it would be really helpful if you could provide your feedback here in the thread, since this is expected to be a rough beta, and we can be less formal here. Once we take care of some of the more egregious issues and wrap up this beta, we can move to using Github for traditional issues/PRs workflow.

When you do post, please try to put as much information into a single post as possible, including details about your system, and relevant terminal output using the code option in the post editor. This will keep the conversation as organized as possible.

Alternatively, if you wish to provide verbal feedback, this is also welcome and you can do so at our weekly Zoom call every Tuesday at 8:00 pacific time.

Thanks in advance for your help! Your feedback will greatly help improve the curriculum contributor experience.

I really like what you’re doing here with this tool and it should make lesson creation super easy.

What I would find super useful is when using the ?, have a URL as part of the output to lead the user to a page for help on each section. I asked myself a couple of times questions like “What does it mean by connections?” and scratched my head a bit trying to remember. The tool assumes the user knows this stuff and an infrequent creator such as myself can’t remember the details to make the best of the tool.

I’m splitting hairs and it’s really great to see this!

@davedotdev Thanks for the feedback. I restructured the way descriptions are displayed, and added links to docs for all resources we currently have docs for. PR here - https://github.com/nre-learning/antidote-core/pull/165

I imagine I’ll be finished by EoD with this, so you should be able to grab the binaries that get compiled tonight and try again if you want.