ENH: Setup Sphinx documetation for readthedocs

Layout proposition for automated online documentation with readthedocs.

CMakeLists.txt

@@ -144,6 +144,11 @@ if(RTK_BUILD_DOXYGEN)
   add_subdirectory(documentation/Doxygen)
 endif()
 
+option(RTK_BUILD_SPHINX "Build Documentation" OFF)
+if(RTK_BUILD_SPHINX)
+  add_subdirectory(documentation/Sphinx)
+endif()
+
 # Setup build locations.
 if(NOT CMAKE_RUNTIME_OUTPUT_DIRECTORY)
   set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${RTK_BINARY_DIR}/bin)

GettingStarted.md

@@ -5,8 +5,8 @@ Here are suggested steps for the RTK beginner.
 
   1. Install the software following [INSTALLATION.md](INSTALLATION.md).
 
-  2. If you are not already familiar with ITK, [get started with ITK](https://github.com/InsightSoftwareConsortium/ITK/blob/master/GettingStarted.md).
+  2. If you are not already familiar with ITK, [get started with ITK](https://github.com/InsightSoftwareConsortium/ITK/blob/master/GettingStarted.md#L1).
 
-  3. Check out the [FirstReconstruction](examples/FirstReconstruction) example (both the [CMake](examples/FirstReconstruction/CMakeLists.txt) and the [C++](examples/FirstReconstruction/FirstReconstruction.cxx) codes). Many other examples are on the wiki using the applications (corresponding source code in the [applications](applications) subdirectory).
+  3. Check out the [FirstReconstruction](https://github.com/SimonRit/RTK/blob/master/examples/FirstReconstruction) example (both the [CMake](https://github.com/SimonRit/RTK/blob/master/examples/FirstReconstruction/CMakeLists.txt) and the [C++](https://github.com/SimonRit/RTK/blob/master/examples/FirstReconstruction/FirstReconstruction.cxx) codes). Many other examples are on the wiki using the applications (corresponding source code in the [applications](https://github.com/SimonRit/RTK/blob/master/applications) subdirectory).
 
   4. Ask question to the [user mailing list](http://public.kitware.com/mailman/listinfo/rtk-users).

conf.py

@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+#import os
+#import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import subprocess
+
+# -- Build setup -------------------------------------------------------------
+def setup(app):
+  # Fetch documentation images
+  subprocess.check_call("cmake -P documentation/Sphinx/ExternalData/FetchExternalData.cmake", stderr=subprocess.STDOUT, shell=True)
+
+# -- Project information -----------------------------------------------------
+
+project = 'RTK'
+copyright = '2020, Simon Rit'
+author = 'Simon Rit'
+
+# The full version, including alpha/beta/rc tags
+release = '2.1.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['recommonmark']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Master document -------------------------------------------------
+master_doc = 'index'

documentation/Sphinx/CMakeLists.txt

@@ -0,0 +1,37 @@
+if(RTK_BUILD_SPHINX)
+
+  set(RTK_DOC_OUTPUT_DIR ${CMAKE_BINARY_DIR}/documentation)
+
+  # We must also duplicate the source tree since the images need to be present
+  # with the source.
+  add_custom_target(copy_sources ALL
+    COMMAND ${CMAKE_COMMAND} -E copy_directory "${RTK_SOURCE_DIR}/examples" "${RTK_DOC_OUTPUT_DIR}/examples"
+    COMMAND ${CMAKE_COMMAND} -E copy_directory "${RTK_SOURCE_DIR}/documentation" "${RTK_DOC_OUTPUT_DIR}/documentation"
+    COMMAND ${CMAKE_COMMAND} -E copy "${RTK_SOURCE_DIR}/index.rst" "${RTK_DOC_OUTPUT_DIR}/index.rst"
+    COMMAND ${CMAKE_COMMAND} -E copy "${RTK_SOURCE_DIR}/conf.py" "${RTK_DOC_OUTPUT_DIR}/conf.py"
+    COMMAND ${CMAKE_COMMAND} -E copy "${RTK_SOURCE_DIR}/GettingStarted.md" "${RTK_DOC_OUTPUT_DIR}/GettingStarted.md"
+    COMMAND ${CMAKE_COMMAND} -E copy "${RTK_SOURCE_DIR}/INSTALLATION.md" "${RTK_DOC_OUTPUT_DIR}/INSTALLATION.md"
+    COMMENT "Copying documentation sources"
+    )
+
+  find_program(SPHINX_EXECUTABLE
+    NAMES sphinx-build sphinx-build.exe
+    DOC "Sphinx documentation generator"
+  )
+
+  add_custom_target( sphinx_doc ALL
+    COMMAND ${SPHINX_EXECUTABLE}
+    -c ${RTK_DOC_OUTPUT_DIR}
+    ${RTK_DOC_OUTPUT_DIR}
+    "${RTK_DOC_OUTPUT_DIR}/sphinx_output"
+    COMMENT "Generating sphinx documentation"
+    WORKING_DIRECTORY ${RTK_DOC_OUTPUT_DIR}
+    )
+
+  set_property(
+    DIRECTORY APPEND PROPERTY
+    ADDITIONAL_MAKE_CLEAN_FILES
+    "${RTK_DOC_OUTPUT_DIR}/sphinx_output"
+    )
+
+endif()

documentation/Sphinx/ExternalData/FetchExternalData.cmake

@@ -0,0 +1,28 @@
+# Fetch external data from https://data.kitware.com
+# Used by Sphinx conf.py during setup.
+#
+set(link_content sha512)
+
+if(NOT EXTERNAL_DATA_INPUT_ROOT)
+  set(EXTERNAL_DATA_INPUT_ROOT "${CMAKE_SOURCE_DIR}")
+endif()
+
+if(NOT EXTERNAL_DATA_OUTPUT_ROOT)
+  set(EXTERNAL_DATA_OUTPUT_ROOT "${CMAKE_SOURCE_DIR}")
+endif()
+
+file(GLOB_RECURSE content_files
+  "${EXTERNAL_DATA_INPUT_ROOT}/*${link_content}")
+
+foreach(content_file ${content_files})
+
+  file(RELATIVE_PATH content_file_rel_path ${EXTERNAL_DATA_INPUT_ROOT} ${content_file})
+  get_filename_component(last_ext "${content_file_rel_path}" LAST_EXT)
+  string(REPLACE "${last_ext}" "" content_file_rel_path "${content_file_rel_path}")
+
+  file(READ "${content_file}" hash)
+  set(URL "https://data.kitware.com:443/api/v1/file/hashsum/${link_content}/${hash}/download")
+  string(REGEX REPLACE "\n" "" URL "${URL}")
+  file(DOWNLOAD "${URL}" "${EXTERNAL_DATA_OUTPUT_ROOT}/${content_file_rel_path}")
+
+endforeach()

documentation/Sphinx/requirements.txt

@@ -0,0 +1,2 @@
+cmake
+recommonmark

examples/FDK/Code2D.sh

@@ -0,0 +1,12 @@
+# Create a simulated geometry
+rtksimulatedgeometry -n 180 -o geometry.xml
+
+# Create projections of the phantom file
+# Note the sinogram being 3 pixels wide in the y direction to allow back-projection interpolation in a 2D image
+rtkprojectgeometricphantom -g geometry.xml -o projections.mha --spacing 2 --dimension=512,3,512 --phantomfile SheppLogan-2d.txt --phantomscale=256,1,256
+
+# Reconstruct
+rtkfdk -p . -r projections.mha -o fdk.mha -g geometry.xml --spacing 2 --dimension 256,1,256
+
+# Create a reference volume for comparison
+rtkdrawgeometricphantom --spacing 2 --dimension=256,1,256 --phantomfile SheppLogan-2d.txt -o ref.mha --phantomscale=256,1,256

examples/FDK/Code3D.sh

@@ -0,0 +1,12 @@
+# Create a simulated geometry
+rtksimulatedgeometry -n 180 -o geometry.xml
+# You may add "--arc 200" to make the scan short or "--proj_iso_x 200" to offset the detector
+
+# Create projections of the phantom file
+rtkprojectgeometricphantom -g geometry.xml -o projections.mha --spacing 2 --dimension 256 --phantomfile SheppLogan.txt
+
+# Reconstruct
+rtkfdk -p . -r projections.mha -o fdk.mha -g geometry.xml --spacing 2 --dimension 256
+
+# Create a reference volume for comparison
+rtkdrawgeometricphantom --spacing 2 --dimension 256 --phantomfile SheppLogan.txt -o ref.mha

examples/FDK/Documentation.rst

@@ -0,0 +1,43 @@
+=====
+ FDK
+=====
+
+Reconstruction of the Shepp–Logan phantom using Feldkamp, David and Kress cone-beam reconstruction.
+
+3D
+==
+|sin_3D| |img_3D|
+
+This script uses the file `SheppLogan.txt`_ as input.
+
+.. literalinclude:: Code3D.sh
+
+.. _SheppLogan.txt: https://data.kitware.com/api/v1/item/5b179c938d777f15ebe2020b/download
+
+.. |sin_3D| image:: SheppLogan-3D-Sinogram.png
+  :scale: 30%
+  :alt: Shepp-Logan 3D sinogram
+
+.. |img_3D| image:: SheppLogan-3D.png
+  :scale: 30%
+  :alt: Shepp-Logan 3D image
+
+2D
+==
+|sin_2D| |img_2D|
+
+The same reconstruction can be performed using the original 2D Shepp-Logan phantom.
+RTK can perform 2D reconstructions through images wide of 1 pixel in the y direction.
+The following script performs the same reconstruction as above in a 2D environment and uses the `2D Shepp-Logan`_ phantom as input.
+
+.. literalinclude:: Code2D.sh
+
+.. _2D Shepp-Logan: http://wiki.openrtk.org/images/7/73/SheppLogan-2d.txt
+
+.. |sin_2D| image:: SheppLogan-2D-Sinogram.png
+  :scale: 50%
+  :alt: Shepp-Logan 2D sinogram
+
+.. |img_2D| image:: SheppLogan-2D.png
+  :scale: 50%
+  :alt: Shepp-Logan 2D image

examples/FDK/SheppLogan-2D-Sinogram.png.sha512

@@ -0,0 +1 @@
+682d8c73cdb927fdfe6c68e224fbd99c9e39f7358eb7cab7964301eb6f83b1140aaa0d3560cdff421e047a2492116896187b01760ba3e195df03c8f2c66c7a4a

examples/FDK/SheppLogan-2D.png.sha512

@@ -0,0 +1 @@
+7512e4922f53f636b0867a7440627173e58d05f43d9fd6770e16dab2fc6073b5cff5a0e9c7734da9ffdfd2b4f111a828dd7df642ab8cccd8ef9f195b5e8a1dab

examples/FDK/SheppLogan-3D-Sinogram.png.sha512

@@ -0,0 +1 @@
+6f448c7ff88f2703dbf5e0ca226c441d819b74785992a5b84cb5ac68b09efab04802e984df603c8f9bbec6fc295719cd947d002740ba99241f41b04e9741d5ec

examples/FDK/SheppLogan-3D.png.sha512

@@ -0,0 +1 @@
+e8ca23464aee187bcd8d38a3d3bf3f2907e4e3e3a04fdee7cced6cf88031358abbc9a3dbeb3c441414de29554328d05690d4f5229cb2fd406757babe32d80f2c

examples/index.rst

@@ -0,0 +1,7 @@
+Examples
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   ./FDK/Documentation.rst

index.rst

@@ -0,0 +1,13 @@
+.. RTK documentation master file, created by
+   sphinx-quickstart on Mon Apr 27 09:12:40 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to RTK's documentation!
+===============================
+
+.. toctree::
+  :maxdepth: 2
+
+  /GettingStarted.md
+  examples/index.rst