ENH: Add notebook documentation with nbsphinx extension

[tbirdso]

Add Jupyter Notebook printouts to Sphinx documentation. Resolves Issue 204.

[tbirdso]

@thewtex The CI documentation build check succeeds when the nbsphinx extension is included via pip install rather than built from source as a submodule as we had briefly discussed before. Is it reasonable to include the PyPi package as an extra dependency for documentation? Note that nbsphinx also requires pandocs to be installed in the environment via apt.

[thewtex]

@tbirdso excellent!

Due to the pandoc dependency, which may be more difficult to obtain on Windows for example, can we add nbsphinx as a pip install dependency, but as a CMake configuration option that is OFF by default?

[tbirdso]

@thewtex Do we need additional checks if we are intending to build documentation on Windows and macOS? Current documentation checks cover Ubuntu 18.04 only.

pandocs has a basic installer for Windows, is there more difficulty involved with building with nbsphinx or other extensions than running the installer?

nbsphinx is building markup blocks from within .rst files. Is there a way to conditionally build these blocks based on CMake variables?

[thewtex]

@thewtex Do we need additional checks if we are intending to build documentation on Windows and macOS? Current documentation checks cover Ubuntu 18.04 only.

Windows and macOS CI documentation builds would be good.

nbsphinx is building markup blocks from within .rst files. Is there a way to conditionally build these blocks based on CMake variables?

The content of conf.py could be configured based on the CMake variable and conf.py.in to conditionally add the nbsphinx extension. Do the markup blocks with *.ipynb cause documentation build failures if the nbsphinx extension is net enabled?

pandocs has a basic installer for Windows, is there more difficulty involved with building with nbsphinx or other extensions than running the installer?

If this is easy enough, we could add a check for the availability of the executable with CMake find_executable, and provide installation instructions if it is not available (we should probably do this for Ubuntu, at least). On macOS, these type of dependencies are usually installed with HomeBrew, e.g. brew install pandoc.

[tbirdso]

@thewtex I've tested disabling nbsphinx while leaving Jupyter Notebook references in each respective Documentation.rst file in a local branch tbirdso/nbsphinx-check-errors-disabled. Several warnings are logged in CDash indicating that sphinx cannot link the notebook files in each toctree without nbsphinx installed, and the CI check fails:

WARNING: toctree contains reference to nonexisting document 'src/Core/Transform/MutualInformationAffine/MutualInformationAffine.ipynb'

WARNING: toctree contains reference to nonexisting document 'src/Numerics/Optimizers/ExhaustiveOptimizer/PlotExhaustiveOptimizer.ipynb'

WARNING: toctree contains reference to nonexisting document 'src/Registration/Common/MutualInformation/MutualInformation.ipynb'

WARNING: toctree contains reference to nonexisting document 'src/Registration/Metricsv4/RegisterTwoPointSets/RegisterTwoPointSets.ipynb'

Is there another way to conditionally link blocks in .rst documents based on whether nbsphinx and pandocs available? If not, is it preferable to add a check for the pandocs CMake dependency when BUILD_DOCUMENTATION is enabled?

[thewtex]

If not, is it preferable to add a check for the pandocs CMake dependency when BUILD_DOCUMENTATION is enabled?

Yes, let's do this instead.

[thewtex]

@tbirdso could this please be rebased on master for updated CI?

[tbirdso]

@thewtex It seems like pandoc does need to be in the PATH for nbsphinx to run in building documentation. nbsphinx docs note:

The use of pandoc in nbsphinx is temporary, but will likely stay that way for a long time, see issue
#3617

We can take a look at pypandoc as an alternative installation process but it looks like that might not be maintained?