Update Github IO

[blowekamp]

89a1b36#commitcomment-18514290

[zivy]

This issue will never be closed - serves as a reminder to keep the github pages up to date.

[manting12]

how to load the data used by examples of the SimpleITK-Notbooks?

Any reply would be appreciated!

[zivy]

Hello @manting12

Please ask your question on itk discourse. Also please elaborate as it is not clear what is the problem you are having. Possibly take a look at the setup notebook which downloads all of the data to the 'Data' directory?

[kolibril13]

@blowekamp , @zivy :
The notebooks are already two years old:

Therefore, the question: Could you please update them?
Also, the website is a bit difficult to navigate; One has first to click on these sections to access the links to the notebooks, and then it is not possible to navigate from notebook to notebook.

Therefore, my suggestion: Why not using sphinx builds to render the notebooks?
I've done this before, and it is really convenient to use and to navigate. I just stitched together a minimal example using itk to show you the concept of what I mean.
https://okapi3.readthedocs.io/en/latest/ch1.html
And here is what happens:
The not executed notebooks are sent to a sphinx pipeline.
At the web service readthedocs all notebooks are executed and rendered to nice HTML pages, including a search bar and copy buttons for the notebook cells.
I think this would be a great benefit to make these itk notebooks more accessible.

[zivy]

Hello @kolibril13,

Updating the notebooks is a manual process. We have made several attempts to automate it (issue #267) but unsuccessfully. Originally we tried running nbconvert, exporting to html. @jwj019 tried with several other tools, don't remember which specifically (@jwj019 can you list the tools and issues you encountered?).

The issues I remember are:

1. We have cells that have intentional errors, raising an exception that the reader needs to correct. This kills everything starting with the cell containing the error and everything after it.
2. Interactive figures (images + ipywidgets) are not rendered correctly, GUI controls are not visible.

If you are willing to work with us on automating the process we would be more than happy to help you along.

[kolibril13]

Hello @zivy,
thanks a lot for your reply. My attempt to do this would be with using nbsphinx
Regarding point 1:
With this parameter: nbsphinx_allow_errors = True will throw an error for one cell, but will go on executing the next one.
https://github.com/kolibril13/okapi3/blob/ad8eae04c90b662bef2e3960c4df6fc5ce5e792e/docs/source/conf.py#L37
Regarding point 2:
Yes, that will be really difficult to automate!

Therefore, I want to suggest a new idea, that will be based on pre-rendered notebooks, but with a better page layout.
Currently, it is really difficult to navigate the webpage, and also my browser gives me a security warning when entering http://insightsoftwareconsortium.github.io/SimpleITK-Notebooks/

And here is the webpage: it is build with the prerndered notebooks, sphinx, nbsphinx, furo theme, and sphinx-copybutton:
https://okapi3--3.org.readthedocs.build/en/3/02_Pythonic_Image.html
Advantage of this approach over the current side:

• No security warning
• search bar
• navigation bar on the left between notebooks
• navigation bar on the right within one notebook
• easy to copy cells
  Here is the rendered page:
  https://okapi3--3.org.readthedocs.build/en/3/02_Pythonic_Image.html
  and here is the associated pull request: https://github.com/kolibril13/okapi3/pull/3
  Screenshot:
  

[kolibril13]

I've now added all the notebooks, and found that the markdown level of headings have to be adjusted in order to be shown correctly on the right navigation bar:

nbsphinx wants to have the Markdown syntax # H1 ## H2 etc., and does not support the current headings with <h1 align="center">.

In case that this new nbsphinx gallery at readthedocs with pre-rendered notebooks is wanted, these are the steps that would be needed to be taken:

1. Change the headings of the chapters.
2. Run all notebooks
3. Add this project to the readthedocs page.

I am motivated to spend some time on this, if this is a wanted feature.

[zivy]

Hello @kolibril13,

First of all, thank you for putting the effort into this.

Changing the chapter headings should be fine.

I did a quick browse of the site and it looks like we will need to go over all notebooks to confirm that they render correctly and modify if not (for example the table at the top of this page renders correctly for some rows and has problems with others). These changes should be done incrementally so that we can check that every notebook is rendered correctly and that the desired functionality is maintained (just separate commits for each one).

The table on the left side is a bit confusing as it lists all the headers from all notebooks at the same level. Is there a way to create a hierarchy (notebook header->sub headers) or do we only list the notebook top heading?

Finally, we currently host the notebooks using GitHub pages. Is there some requirement that we go to Read-The-Docs, or can we keep the static site where it is?

[kolibril13]

Hi zivy,

Changing the chapter headings should be fine.

Perfect, I can make a pull request for that soon.

for example the table at the top of this page renders correctly for some rows and has problems with others

Good catch, I did not see that. That would mean there will be some extra steps involved, but I think in the end it would be worth it.

These changes should be done incrementally

Yes, I agree with that!

The table on the left side is a bit confusing as it lists all the headers from all notebooks at the same level. Is there a way to create a hierarchy (notebook header->sub headers) or do we only list the notebook top heading?

On the left bar, it shows all chapter names with a "#h1" in it.
Adjusting this will make it look cleaner.
Also, it would be possible to divide the notebooks into chapters, with e.g. each chapter containing 5-10 notebooks
Here is a screenshot from another project:

Finally, we currently host the notebooks using GitHub pages. Is there some requirement that we go to Read-The-Docs, or can we keep the static site where it is?

This is indeed possible, I just searched on the internet and found this tutorial https://daler.github.io/sphinxdoc-test/includeme.html
However, Readthedocs has an amazing infrastructure (different versions of this gallery possible, building from a pull request), so I'd slightly prefer that. Only drawback: a bit of advertisement at the end of the page:

https://simpleitk.readthedocs.io/

[zivy]

Hello @kolibril13,

Really appreciate your enthusiasm with SimpleITK and the notebooks.

In the previous PR you added functionality (cmap), but also made more than a few formatting changes. I admit the notebook formatting is not consistent, and we never bothered about it much. But now you have motivated me to give all the notebooks a makeover with the black Python formatter. So, please hold off on additional code formatting.

Again, really appreciate your efforts and hopefully we'll be able to update the static notebook display to a RTD site via your upcoming PR shortly.

[gattia]

@kolibril13 Just wanted to send a note that I've been following some of these issues/pull requests about updating the docs. I've finally had a reason to look at the docs recently (simpleitk.readthedocs.io) and they are so much easier to navigate! Thank you so much for initiating this! They look awesome!