Tutorials & description

[mariuszhermansdorfer]

We need a way to inform future users on what SandWorm can do and how to get there. Some ideas:

1. Example files
2. Video tutorials
3. Wiki page
4. Extended Readme
5. More in-depth workflow descriptions, similar to what @philipbelesky did for Groundhog

[philipbelesky]

Would this all be best bundled as part of a website? Not sure what your background in web development is like, but I would recommend going with a Jekyll site and its integration with Github pages. It wouldn't allow for a true anyone-can-edit-this Wiki, but it means we can keep documentation in the repository source and easily bundle updates to the site/resources with releases.

If that sounds good I can setup the basic infrastructure and maybe do some light customisation of an off the shelf theme.

[mariuszhermansdorfer]

Sounds good to me. Let's use GitHub Pages and Jekyll.
I could purchase a domain for our project. Should we go with sandworm.la?

[philipbelesky]

Great, will add a PR in a sec that has the basic structure. A .ladomain works, good to see it catch on!

[mariuszhermansdorfer]

Domain sandworm.la is ours now. Where should I point it to?

[philipbelesky]

The instructions should be over here. The instructions for enabling the page itself are also located here (enabling it requires full repo access). I guess we could enable it sooner rather than later (along with a 'work in progress note'?) as I don't imagine it will be linked to anywhere.

[mariuszhermansdorfer]

Done. Both sandworm.la and www.sandworm.la should be pointing to the docs now

[mariuszhermansdorfer]

Btw, this is the error message I’m getting:

The page build completed successfully, but returned the following warning for the master branch:

You are attempting to use a Jekyll theme, "just-the-docs", which is not supported by GitHub Pages. Please visit https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fpages.github.com%2Fthemes%2F&data=02%7C01%7Cmrhe%40ramboll.com%7Cf88fc026deb54aed4aa608d745daf5a4%7Cc8823c91be814f89b0246c3dd789c106%7C1%7C0%7C637054679038640421&sdata=eEohMffYqzNTXJFIbaACQs8HT4RhddIqQZMkVS6%2BKek%3D&reserved=0 for a list of supported themes. If you are using the "theme" configuration variable for something other than a Jekyll theme, we recommend you rename this variable throughout your site. For more information, see https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhelp.github.com%2Fen%2Farticles%2Fadding-a-jekyll-theme-to-your-github-pages-site&data=02%7C01%7Cmrhe%40ramboll.com%7Cf88fc026deb54aed4aa608d745daf5a4%7Cc8823c91be814f89b0246c3dd789c106%7C1%7C0%7C637054679038640421&sdata=YzprfPo1kDJcK8yC17XS8Fbk7br9vaylIEsfb1OTAw8%3D&reserved=0.

For information on troubleshooting Jekyll see:

https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fhelp.github.com%2Farticles%2Ftroubleshooting-jekyll-builds&data=02%7C01%7Cmrhe%40ramboll.com%7Cf88fc026deb54aed4aa608d745daf5a4%7Cc8823c91be814f89b0246c3dd789c106%7C1%7C0%7C637054679038640421&sdata=%2FizgS9D3Xqgv9cMMZvrGIJ3mLelzIhqTsdsZPEn7u2o%3D&reserved=0

If you have any questions you can contact us by replying to this email.

[mariuszhermansdorfer]

Looking at the list of officially supported themes, I like this one:
https://github.com/pages-themes/minimal/blob/master/README.md

[philipbelesky]

Ah, this should be fixed in 051e60, I didn't realise Github uses a different theme loader than standard Jekyll. That fix has also meant the page is live.

If you prefer the look of the minimal theme I can customise our use of the current theme to bring it closer to that style. I'd be keen to try and add a bit more personality that can match the color schemes in the draft logo. Either way, just the docs is probably a better starting theme as it provides features like search, subpages, and a few other things that are useful to build on.

[mariuszhermansdorfer]

@philipbelesky, @BarusXXX, I've put together a promo video for our plugin:
https://www.youtube.com/watch?v=pBd-KBpIJSY

The idea is to share it with the wider community, now that it is officially available. A few questions:

1. Are you OK, with the way I credited your respective institutions?
2. @philipbelesky, should we update the https://www.sandworm.la a bit? I'll record a short tutorial on how to use the plugin, which we could post there. We could also link to our DLA papers.
3. @BarusXXX, do you have any material on the robotic interaction?
4. We could also include the drawings of our setups:
   

Any other ideas?

[philipbelesky]

@philipbelesky, @BarusXXX, I've put together a promo video for our plugin:

Great work! A very fun beat and showcase

Are you OK, with the way I credited your respective institutions?

All good!

@philipbelesky, should we update the https://www.sandworm.la/ a bit? I'll record a short tutorial on how to use the plugin, which we could post there. We could also link to our DLA papers.

That sounds good, I've setup a feature/docs-2.0 branch. Maybe as a starting point the structure would be:

1. Landing (approximately similar to current)
2. Tutorial (new video, plus any others)
3. Setup (drawings of setups, considerations in purchase/DIY)
4. Applications (feature notes / docs)
5. Publications

[mariuszhermansdorfer]

Great! Where does sandworm.la pull the data from? Should we just edit the readme file and it will get mirrored on the website?

[philipbelesky]

The data is in markdown files under docs. The homepage is just index.md while the other pages are contained within folders.

Each markdown file has a header with some template specific information so the README can't be directly mirrored, but the content can be copied over directly.

If you're using the windows linux subsystem it should be pretty easy to get a local installation going. With terminal or powershell it probably needs a Ruby install. I'd be happy to run through the setup if useful! Or, you could write the Markdown directly and we can adjust as we go.

[mariuszhermansdorfer]

Thanks, I'll start with writing te Markdown and see how well this goes.

[mariuszhermansdorfer]

@philipbelesky, I've just put together a short intro video on how to use SW:
https://www.youtube.com/watch?v=YYvz1QlTFQw

Let's update the website now and make it all public soon.

[mariuszhermansdorfer]

I tried updating this file but with mixed results. Some changes were picked up by the website immediately, some didn't go through at all. Here is what I see in the editor:

And on the website:

Is there a way to force-rebuild the content?

[philipbelesky]

I presume the changes in 1798a03 were the ones you saw take effect, but the subsequent commits did not? If so, that should be because the subsequent commits were on a feature branch. Github pages only build from a select branch — currently that is main.

If having per-branch previews of the website was useful, I could setup the site to run on Cloudflare Pages rather than Github (I would need full repo access though).

[philipbelesky]

Oh, also, that's a great tutorial video!

[mariuszhermansdorfer]

Thanks!

There is a slight lag between the commit and the website being rebuild which lead me to believe, that it actually builds from the feature branch. No need to setup per-branch previews of the website. It works well as is.

I've updated some basic info on the Introduction page and marked Applications as not published for now. Couldn't find the footer code to edit this section:

Now we're also live on Food4Rhino. Let me know if you have any content you want to be added there.

[philipbelesky]

Great! The footer string is set over here:

SandWorm/docs/_config.yml

Line 42 in e5a0bda

footer_content: "TODO: Copyright & license details"