Sphinx + ReadTheDocs structure

[kolibril13]

As SimpleITK Notebooks has now a ReadTheDocs page, we can use this issue to think about the infrastructure for converting the notebooks for the documentation.

The situation is the following:
Notebooks are stored in
SimpleITK-Notebooks/Python/
but for the readthedocs, they need to be copied to
SimpleITK-Notebooks/docs/source
I think it is possible to add the SimpleITK-Notebooks/Python as a source folder for sphinx.

Executing all notebooks locally on my machine took me about 30 minutes (I did not stop the time, just approx), , the free plan of the readthedocs page offers 15 minutes build time, so I think notebooks have to build locally for each release.
Pre rendered and empty notebooks take only a few minutes to be rendered, and also empty notebooks that are rendered to empty notebooks at readthedocs also go quickly.

That's why I see the following scenario:

At InsightSoftwareConsortium/SimpleITK-Notebooks can be a new branch called "readthedocs", where pre-executed notebooks are living.
Also, there will be the master branch, that contains the non-executed notebooks.
I highly recommend keeping the "build from pull request" option from readthedocs active, as it will give a preview of new added notebooks to this repo on the simpleitk-notebooks.readthedocs.io website and formatting issues can be quickly checked. Of course, the cells won't be executed there, but for finding basic formatting issues, that will be enough.

Then, once in a while, all notebooks from master can be copied to the readthedocs branch (before that, all previous notebooks on the readthedocs branch will be deleted) and rendered locally with the newest version of sitk. These will be then commited to the readthedocs remote branch. As soon as the page simpleitk-notebooks.readthedocs.io looks good, the notebook publisher can add a tag to the branch with a new release:

And readthedocs will know, that there is a most recent stable version, while older versions will be still kept available.

In the readthedocs settings, we can also adjust that the master branch is hidden, and that the readthedocs branch is the default for visitors of the documentation.

The most important document for sphinx, the index.rst file will have a section like this.
Renaming for new added notebooks should happen manually, right?
But I think it would be also possible to automate this.

.. toctree::
    :maxdepth: 2
    :glob:

    00_Setup.ipynb
    01_Image_Basics.ipynb
    02_Pythonic_Image.ipynb
    03_Image_Details.ipynb
    04_Image_Display.ipynb
    05_Results_Visualization.ipynb
    10_matplotlibs_imshow.ipynb
    11_Progress.ipynb
    20_Expand_With_Interpolators.ipynb
    21_Transforms_and_Resampling.ipynb
    22_Transforms.ipynb
    300_Segmentation_Overview.ipynb
    30_Segmentation_Region_Growing.ipynb
    31_Levelset_Segmentation.ipynb
    32_Watersheds_Segmentation.ipynb
    33_Segmentation_Thresholding_Edge_Detection.ipynb
    34_Segmentation_Evaluation.ipynb
    35_Segmentation_Shape_Analysis.ipynb
    36_Microscopy_Colocalization_Distance_Analysis.ipynb
    51_VH_Segmentation1.ipynb
    55_VH_Resample.ipynb
    56_VH_Registration1.ipynb
    60_Registration_Introduction.ipynb
    61_Registration_Introduction_Continued.ipynb
    62_Registration_Tuning.ipynb
    63_Registration_Initialization.ipynb
    64_Registration_Memory_Time_Tradeoff.ipynb
    65_Registration_FFD.ipynb
    66_Registration_Demons.ipynb
    67_Registration_Semiautomatic_Homework.ipynb
    68_Registration_Errors.ipynb
    69_x-ray-panorama.ipynb
    70_Data_Augmentation.ipynb
    71_Trust_But_Verify.ipynb