convert this repo to a jupyterbook

Question

convert this repo to a jupyterbook

satra opened this issue 3 years ago · 19 comments

@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.

Answer 1 · 2022-06-29T14:31:12.000Z

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

Answer 2 · 2022-06-30T03:45:43.000Z

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.

Answer 3 · 2022-06-30T04:48:57.000Z

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

Answer 4 · 2022-06-30T13:28:12.000Z

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

Answer 5 · 2022-07-06T17:19:45.000Z

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.

Answer 6 · 2022-07-06T17:36:51.000Z

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?

Answer 7 · 2022-07-06T17:40:41.000Z

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?

Answer 8 · 2022-07-06T17:53:04.000Z

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?

Answer 9 · 2022-07-06T18:03:03.000Z

@htwangtw - oh, ok, thanks!

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

Answer 10 · 2022-07-06T18:24:36.000Z

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.

Answer 11 · 2022-07-06T18:39:57.000Z

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?

Answer 12 · 2022-07-06T18:41:41.000Z

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.

Answer 13 · 2022-07-06T18:42:13.000Z

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

Answer 14 · 2022-07-06T18:52:28.000Z

@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.

Answer 15 · 2022-07-06T19:14:25.000Z

@effigies ah, I just saw your link.... I've created a PR, I put back @djarecka original binder link, which specifies the notebook folder. Seems work well.

Answer 16 · 2022-07-07T14:36:16.000Z

@effigies hello, we probably want to go back to our original settings for requirements.txt (use only one file) because jupyterbook also needs to import all packages. We need to add all used packages into jupyterbook/requirements.txt; otherwise, cells can't be executed properly. In that case, would it be better if we only use one requirements.txt?

Answer 17 · 2022-07-07T17:05:30.000Z

Yeah, I think that's fine for now. I can revisit making things more cleanly targeted later, if it still irks me. :-)

Answer 18 · 2022-07-12T19:28:14.000Z

hello @effigies you probably didn't notice this, our jupyterbook can't be executed properly. For example, here https://nipype.github.io/pydra-tutorial/notebooks/4_intro_workflow.html
we have error messages like this

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
Input In [2], in <cell line: 1>()
----> 1 import pydra
      3 # functions used later in the notebook:
      6 @pydra.mark.task
      7 def add_two(x):

ModuleNotFoundError: No module named 'pydra'

I think it's related to the requirements.txt. I can fix it; do you want all python packages in one requirements.txt or separate them into requirments.txt and jupyterbook/requirements.txt. There are overlapping packages for binder and jupyterbook, so maybe we just use one?

Answer 19 · 2022-10-07T16:09:14.000Z

done by Yibei