Put tutorial in a place where it has a stable link to a HTML rendering

[hlapp]

Right now there's only a Markdown file in the repository. We should consider and if not too difficult achieve the following:

• Put link to the tutorial into the README. Ideally this would point to an HTML-rendered version (rather than, say, the Jupyter Notebook).
• Make the tutorial available from the online website.

We should keep in mind that we'll probably want to add the tutorial also as supplementary material to the manuscript. This could be done using HackMD and the Markdown version, but it be preferable is there were simply a HTML version that we could then archive to a PDF and submit as supplementary document.

[gaurav]

Make the tutorial available from the online website.

This is very easy to do, and I've done it in PR #103.

Put link to the tutorial into the README. Ideally this would point to an HTML-rendered version (rather than, say, the Jupyter Notebook).

Once PR #103 has been merged, there will be two versions of this file that we could use to do this:

1. The Markdown version of the file at https://github.com/phyloref/phyx.js/blob/master/tutorial/Introduction%20to%20phyx.js.md
2. The HTML version of the file, which will be similar to the HTML version of the CHANGELOG currently on the ESDoc website at https://www.phyloref.org/phyx.js/manual/CHANGELOG.html

I think the second option would be better. What do you think?

Note that the Jupyter Notebook is itself rendered on both GitHub and (more reliably) on the Jupyter Notebook Viewer. I think we should link to the Jupyter Notebook Viewer from the README as well. What do you think? If you approve, I'll make this changes in PR #103 as well.

We should keep in mind that we'll probably want to add the tutorial also as supplementary material to the manuscript. This could be done using HackMD and the Markdown version, but it be preferable is there were simply a HTML version that we could then archive to a PDF and submit as supplementary document.

We could use either of the HTML versions listed above, but neither of them do a good job with the long lines of source code in our tutorial. I tried to convert the Markdown file into an HTML file, which looks better to me but also has the same issue. I also tried to generate a PDF from within Jupyter Notebook -- this would also require some tweaking, but produces a pretty readable PDF.

I think the best solution might be to convert the Markdown file into a PDF via pandoc -- the Eisvogel template allows us to tweak the source code font size and has good support for wrapping source code lines. I had to change the Markdown slightly to make the PDF output work, since Jupyter Notebook writes out program output as normal code blocks (indented by four spaces) rather than fenced code blocks (starting and ending with ```), which is rendered very differently in Pandoc. But if we decide that this is the best approach, I could add a small script to do this into the repository.

I've used PR #103 to store some of the possible supplementary materials file -- once we decide about the best approach, I'll delete the alternatives we don't need and add a README to record how we generated this file.

[gaurav]

• Decision: let's use the Notebook Viewer link, and be careful about exactly which version we want to link with (e.g. in the paper, we can cite the one relating to the current version, while the README could refer to the Markdown version).
• Add a note to the README to indicate that the Notebook is viewable in NBviewer, but not in runnable in Binder yet.
• Look into whether we can configure the Notebook so that Binder brings up the IJavascript kernel rather than the Python3 kernel. Not important for this paper, but file as an issue to tackle later.

[gaurav]

• We don't need the HTML file in the manual, but we do need a link to it in the Jupyter Notebook Viewer.

[gaurav]

Okay, here's what we have now:

1. The Introduction tutorial in Markdown format is linked from the README file.
2. A README in the tutorials/ directory contains links to the Introduction tutorial as a Jupyter Notebook in GitHub, as a Markdown file, and as a PDF. It also includes a button to open the tutorials/ directory in nbviewer.
3. An HTML version of this tutorial is also available in our manual at https://www.phyloref.org/phyx.js/manual/Introduction.html
4. Integrating with Binder isn't doable yet, but I've opened an issue to fix that eventually: Add support for running tutorial notebooks in MyBinder #105
   • I've also added a note to the README indicating this in PR Added note that Binder cannot be used #110

This is a slightly different approach to what we discussed last week, which was to focus on nbviewer, but GitHub seems to render the Jupyter Notebook pretty quickly without any bugs, so I think this is probably the better approach for now. Links to nbviewer are also available in the tutorials README file, although the main README file only links directly to the Markdown version of the tutorial.

Hilmar: what do you think of this approach? Let me know if you think we should do something differently. Otherwise, I think we can close this issue.

[hlapp]

This sounds fine, I agree we are done with this. Note that the HTML version renders the front matter metadata in a less-than-ideal way, but that's a cosmetic issue we can try to fix down the road.