convert this repo to a jupyterbook

[satra]

@djarecka and @yibeichan - it may be worthwhile to spend a bit of time to convert this repo to a jupyterbook. it shouldn't be too hard and it will make the notebooks easier to diff and read since they will be in myst/markdown, and the site will be generated through continuous integration ensuring that the notebooks work with the latest versions of software.

[yibeichan]

Hello, I'm okay with converting it to a jupyterbook. Always want to try.

[yibeichan]

Hello, I made this jupyterbook. It works, though I do need to fix some errors.
Currently this book is under my github account, because I used master(I should have used a different branch) for my last PR. Once the glm PR has been merged, I'll move this jupyterbook to a well-named branch and create a new PR.

[yibeichan]

one more good news, hide-cell/hide-output works well in this jupyterbook, see this one https://yibeichan.github.io/pydra-book/notebooks/3_intro_functiontask_state.html#exercise-1

[djarecka]

oh yes, this exercise look great! please let me know when this is ready to review

[effigies]

I merged #26 and set up an action to deploy it: https://nipype.github.io/pydra-tutorial

The binderhub link still doesn't target correctly, but hopefully this is more fixable now.

Our requirements.txt is pretty heavy, taking >1m to install. I think we might want to distinguish the requirements for setting up the binder environment and building the jupyterbook.

The old CI tests no longer do anything because we removed the .ipynb files. I haven't tested if changing to .md works, but it would be good to get back to testing across supported Python versions (3.7-3.10).

Thanks again @yibeichan! Having these notebooks in jupytext form will make it much easier to propose improvements.

[djarecka]

I've never created a jupyter book, but I'm bit confused how to run it with binder or locally - if I click binder logo on this website it works, but after opening jupyter lab I don't see any notebooks that I can run. What am I missing?

[yibeichan]

Thank you! oh maybe I should remove the word "running it locally" in the weclome page and I think if we remove the below from jupyterbook/_config.yml, it should fix the problem with opening each single jupyter notebook in binder

launch_buttons:
  binderhub_url: "https://mybinder.org/v2/gh/nipype/pydra-tutorial/master"

regarding requirments.txt, oh nice, I've never realized that we should separate them for setting up the binder environment and building the jupyterbook? How to separate them? do we create a separate file some where?

[htwangtw]

I've never created a jupyter book, but I'm bit confused how to run it with binder or locally - if I click binder logo on this website it works, but after opening jupyter lab I don't see any notebooks that I can run. What am I missing?

For the jupyter lab layout, you will need to navigate to where the actual text lives (notebooks/) and you will need to right click on the file to select open with Jupyter notebook explicitly.

I am not sure if this is feasible, but it will be great if binder can just launch and start at the directory where the notebooks lives?

[djarecka]

@htwangtw - oh, ok, thanks!

we should probably update the README to specify how to run it locally

[effigies]

regarding requirments.txt, oh nice, I've never realized that we should separate them for setting up the binder environment and building the jupyterbook? How to separate them? do we create a separate file some where?

Binder uses requirements.txt, though I'm not sure if it can be configured to use something else. For jupyterbook, we can create either jupyterbook/requirements.txt or doc-requirements.txt and install that in our gh-pages.yml action.

[yibeichan]

For the jupyter lab layout, you will need to navigate to where the actual text lives (notebooks/) and you will need to right click on the file to select open with Jupyter notebook explicitly.
I am not sure if this is feasible, but it will be great if binder can just launch and start at the directory where the notebooks lives?

@effigies How about we keep .ipynb files but put .md files into .gitignore, would it be more straightforward for users?

[effigies]

For the jupyter lab layout, you will need to navigate to where the actual text lives (notebooks/) and you will need to right click on the file to select open with Jupyter notebook explicitly.
I am not sure if this is feasible, but it will be great if binder can just launch and start at the directory where the notebooks lives?

@effigies How about we keep .ipynb files but put .md files into .gitignore, would it be more straightforward for users?

Putting .md files in gitignore would defeat the whole purpose here, IMO. Notebooks that can be inspected as plain text is a huge plus. I would probably just switch from the lab interface to the tree interface, which will correctly interpret them as notebooks.

[htwangtw]

For the jupyter lab layout, you will need to navigate to where the actual text lives (notebooks/) and you will need to right click on the file to select open with Jupyter notebook explicitly.
I am not sure if this is feasible, but it will be great if binder can just launch and start at the directory where the notebooks lives?

@effigies How about we keep .ipynb files but put .md files into .gitignore, would it be more straightforward for users?

You should be able to enable download notebook in the _congfig.yml file
It's already there. All we need is a line in the home page to point that out.
Alternatively, feel free to steal what I have here

[effigies]

@yibeichan IDK if you saw https://the-turing-way.netlify.app/communication/binder/zero-to-binder.html#by-changing-the-mybinder-org-launch-link? This shows how to change the target to use the classic notebook interface instead of jupyterlab.