From acb0f46da66013eddced8df1c8b7e31549bb072f Mon Sep 17 00:00:00 2001
From: David Thompson <david.thompson@kitware.com>
Date: Tue, 23 Jun 2015 19:53:59 -0400
Subject: [PATCH] First pass at building documentation.
Both Doxygen (ninja/make target `doc`)
and Sphinx (ninja/make target `doc-userguide`)
documentation are built.
The Doxygen documentation is put in `documentation/reference/SimMedTK`
while the Sphinx documentation is put in `documentation/user`.
This should close issue #3. (Actually finishing writing the
documentation should probably be several separate issues covering more
specific parts of the documentation.)
---
.gitignore | 1 +
CMake/FindSphinx.cmake | 51 ++
CMake/SimMedTKSphinxDocs.cmake | 39 ++
CMakeLists.txt | 40 +-
documentation/CMakeLists.txt | 62 +++
.../{Doxyfile => SimMedTK.doxyfile.in} | 23 +-
documentation/conf.py | 457 ++++++++++++++++++
documentation/findfigure.py | 205 ++++++++
documentation/index.rst | 26 +
documentation/requirements/dev.txt | 8 +
documentation/userguide/administration.rst | 116 +++++
documentation/userguide/contributing.rst | 161 ++++++
.../userguide/figures/SimMedTK-logo.svg | 284 +++++++++++
documentation/userguide/index.rst | 34 ++
14 files changed, 1484 insertions(+), 23 deletions(-)
create mode 100644 CMake/FindSphinx.cmake
create mode 100644 CMake/SimMedTKSphinxDocs.cmake
create mode 100644 documentation/CMakeLists.txt
rename documentation/{Doxyfile => SimMedTK.doxyfile.in} (99%)
create mode 100644 documentation/conf.py
create mode 100644 documentation/findfigure.py
create mode 100644 documentation/index.rst
create mode 100644 documentation/requirements/dev.txt
create mode 100644 documentation/userguide/administration.rst
create mode 100644 documentation/userguide/contributing.rst
create mode 100644 documentation/userguide/figures/SimMedTK-logo.svg
create mode 100644 documentation/userguide/index.rst
diff --git a/.gitignore b/.gitignore
index 9ba231e04..a0e0ac552 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
win32
+documentation/findfigure.pyc
diff --git a/CMake/FindSphinx.cmake b/CMake/FindSphinx.cmake
new file mode 100644
index 000000000..c8f72f335
--- /dev/null
+++ b/CMake/FindSphinx.cmake
@@ -0,0 +1,51 @@
+# - This module looks for Sphinx
+# Find the Sphinx documentation generator
+#
+# This modules defines
+# SPHINX_EXECUTABLE
+# SPHINX_FOUND
+find_program(SPHINX_EXECUTABLE
+ NAMES sphinx-build
+ PATHS
+ /usr/bin
+ /usr/local/bin
+ /opt/local/bin
+ DOC "Sphinx documentation generator"
+)
+
+if( NOT SPHINX_EXECUTABLE )
+ set(_Python_VERSIONS
+ 2.7 2.6 2.5 2.4 2.3 2.2 2.1 2.0 1.6 1.5
+ )
+ foreach( _version ${_Python_VERSIONS} )
+ set( _sphinx_NAMES sphinx-build-${_version} )
+ find_program( SPHINX_EXECUTABLE
+ NAMES ${_sphinx_NAMES}
+ PATHS
+ /usr/bin
+ /usr/local/bin
+ /opt/loca/bin
+ DOC "Sphinx documentation generator"
+ )
+ endforeach()
+endif()
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(Sphinx DEFAULT_MSG SPHINX_EXECUTABLE)
+mark_as_advanced(SPHINX_EXECUTABLE)
+
+function(Sphinx_add_target target_name builder conf source destination)
+
+ add_custom_target(${target_name} ALL
+ COMMAND ${SPHINX_EXECUTABLE} -b ${builder}
+ -c ${conf}
+ ${source}
+ ${destination}
+ COMMENT "Generating sphinx documentation: ${builder}"
+ )
+
+ set_property(DIRECTORY
+ APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES ${destination}
+ )
+
+endfunction()
diff --git a/CMake/SimMedTKSphinxDocs.cmake b/CMake/SimMedTKSphinxDocs.cmake
new file mode 100644
index 000000000..2953727e4
--- /dev/null
+++ b/CMake/SimMedTKSphinxDocs.cmake
@@ -0,0 +1,39 @@
+function(simmedtk_add_doc sphinxTargetName)
+ set(options)
+ set(oneValueArgs DESTINATION SOURCE_DIR BUILD_DIR)
+ set(multiValueArgs DEPENDS FIGURES)
+ cmake_parse_arguments(sphinx "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )
+ if (NOT sphinx_SOURCE_DIR)
+ set(sphinx_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}") # Reasonable default
+ endif()
+ if (NOT sphinx_BUILD_DIR)
+ set(sphinx_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}") # Reasonable default
+ endif()
+ # Generate HTML version of docs
+ set(sphinx_HTML_TOP "${CMAKE_CURRENT_BINARY_DIR}/${sphinx_BUILD_DIR}/html/index.html")
+ add_custom_command(
+ OUTPUT "${sphinx_HTML_TOP}"
+ DEPENDS
+ ${CMAKE_CURRENT_SOURCE_DIR}/conf.py
+ ${sphinx_DEPENDS}
+ ${figureList}
+ COMMAND ${SPHINX_EXECUTABLE}
+ ARGS
+ -b html
+ "${sphinx_SOURCE_DIR}"
+ "${sphinx_BUILD_DIR}/html"
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Generating HTML for ${sphinxTargetName}"
+ )
+ add_custom_target(doc-${sphinxTargetName} DEPENDS "${sphinx_HTML_TOP}")
+ if (sphinx_DESTINATION)
+ install(
+ DIRECTORY "${sphinx_BUILD_DIR}/html/"
+ DESTINATION "${sphinx_DESTINATION}"
+ COMPONENT Development)
+ install(
+ FILES ${figureList}
+ DESTINATION "${sphinx_DESTINATION}/figures"
+ COMPONENT Development)
+ endif()
+endfunction()
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 2def01a0f..5af0a6b28 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -67,6 +67,7 @@ endif()
set(SimMedTK_VERSION_MAJOR 0)
set(SimMedTK_VERSION_MINOR 0)
set(SimMedTK_VERSION_PATCH 1)
+set(SimMedTK_VERSION "${SimMedTK_VERSION_MAJOR}.${SimMedTK_VERSION_MINOR}.${SimMedTK_VERSION_PATCH}")
#-----------------------------------------------------------------------------
# Testing
@@ -75,19 +76,14 @@ option(BUILD_TESTING "Test the project" ON)
include(SimMedTKTesting)
#-----------------------------------------------------------------------------
-# Documentation
+# Documentation options
#
-option(DOCUMENTATION_TARGET_IN_ALL "Include the custom target for building documentation in 'all'" OFF)
-mark_as_advanced(DOCUMENTATION_TARGET_IN_ALL)
-
-set(DOCUMENTATION_ARCHIVES_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
- CACHE PATH "Where documentation archives should be stored")
-mark_as_advanced(DOCUMENTATION_ARCHIVES_OUTPUT_DIRECTORY)
-
-#-----------------------------------------------------------------------------
-# Attempt to discover Doxygen so that DOXYGEN_EXECUTABLE is set to an appropriate default value
-#
-FIND_PACKAGE(Doxygen QUIET)
+option(SimMedTK_ENABLE_DOCUMENTATION
+ "Include targets for Doxygen- and Sphinx-generated documentation" OFF)
+if (SimMedTK_ENABLE_DOCUMENTATION)
+ find_package(Doxygen)
+ find_package(Sphinx)
+endif()
#-----------------------------------------------------------------------------
# Coverage
@@ -246,6 +242,24 @@ if(SimMedTK_USE_OCULUS)
endif()
add_subdirectory(src)
+
+add_subdirectory(examples)
+
+################################################################################
+# Build documentation
+# This also includes tutorials and other documentation that runs
+# examples and/or has its source linked to libraries, so it must
+# come after those targets have been declared.
+#
+
+if (SimMedTK_ENABLE_DOCUMENTATION)
+ add_subdirectory(documentation)
+endif()
+
+################################################################################
+# Create and install package configuration files.
+#
+
export(PACKAGE SimMedTK)
export(TARGETS
${SimMedTK_exports}
@@ -259,5 +273,3 @@ configure_file(
"${CMAKE_CURRENT_BINARY_DIR}/SimMedTKConfig.cmake"
@ONLY
)
-
-add_subdirectory(examples)
diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt
new file mode 100644
index 000000000..1f358134c
--- /dev/null
+++ b/documentation/CMakeLists.txt
@@ -0,0 +1,62 @@
+####### SimMedTK Documentation
+## Reference Documentation
+#
+# If we have doxygen, create reference API documentation for SimMedTK.
+#
+# This also generates documentation for third-party libraries
+# cJSON and sparsehash which is referenced by SimMedTK's documentation.
+#
+if(DOXYGEN_FOUND)
+ file(MAKE_DIRECTORY "${SimMedTK_BINARY_DIR}/documentation/reference")
+ configure_file(
+ ${CMAKE_CURRENT_SOURCE_DIR}/SimMedTK.doxyfile.in
+ ${CMAKE_CURRENT_BINARY_DIR}/SimMedTK.doxyfile
+ @ONLY
+ )
+ add_custom_command(
+ OUTPUT ${SimMedTK_BINARY_DIR}/doc/reference/SimMedTK.tags
+ COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/SimMedTK.doxyfile
+ WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/reference"
+ DEPENDS
+ "${CMAKE_CURRENT_BINARY_DIR}/SimMedTK.doxyfile"
+ # TODO: Add tag files for external dependencies here.
+ COMMENT "Generating SimMedTK API documentation with Doxygen" VERBATIM
+ )
+ add_custom_target(doc
+ DEPENDS ${SimMedTK_BINARY_DIR}/doc/reference/SimMedTK.tags
+ )
+endif(DOXYGEN_FOUND)
+
+## End-user Documentation
+#
+# If we have rst2html, create the user's guide for SimMedTK
+# as an HTML document.
+
+# Define a macro for processing reStructuredText files
+# if docutils were found.
+if (SPHINX_FOUND)
+ include(SimMedTKSphinxDocs)
+ set(SimMedTK_USERGUIDE_DOCS
+ index.rst
+ userguide/index.rst
+ userguide/contributing.rst
+ userguide/administration.rst
+ )
+ if (DOXYGEN_FOUND)
+ # Need doxygen docs built if possible
+ list(APPEND SimMedTK_USERGUIDE_DOCS
+ ${SimMedTK_BINARY_DIR}/documentation/reference/SimMedTK.tags)
+ endif()
+
+ set(SimMedTK_USERGUIDE_FIGS
+ #userguide/figures/architecture.svg
+ )
+ # Add the top-level reStructuredText file.
+ # All others are included by it.
+ simmedtk_add_doc(userguide
+ DEPENDS ${SimMedTK_USERGUIDE_DOCS}
+ FIGURES ${SimMedTK_USERGUIDE_FIGS}
+ BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/user
+ DESTINATION share/doc/SimMedTK/userguide
+ )
+endif()
diff --git a/documentation/Doxyfile b/documentation/SimMedTK.doxyfile.in
similarity index 99%
rename from documentation/Doxyfile
rename to documentation/SimMedTK.doxyfile.in
index 25a373bfd..d950545e9 100644
--- a/documentation/Doxyfile
+++ b/documentation/SimMedTK.doxyfile.in
@@ -38,7 +38,7 @@ PROJECT_NAME = SimMedTK
# could be handy for archiving the generated documentation or if some version
# control system is used.
-PROJECT_NUMBER = v1.0
+PROJECT_NUMBER = "@SimMedTK_VERSION@"
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
@@ -58,7 +58,7 @@ PROJECT_LOGO = Temporary_logo.png
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
-OUTPUT_DIRECTORY = .
+OUTPUT_DIRECTORY = @SimMedTK_BINARY_DIR@/documentation/reference/SimMedTK
# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub-
# directories (in 2 levels) under the output directory of each output format and
@@ -150,7 +150,7 @@ INLINE_INHERITED_MEMB = NO
# shortest path that makes the file name unique will be used
# The default value is: YES.
-FULL_PATH_NAMES = NO
+FULL_PATH_NAMES = YES
# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
# Stripping is only done if one of the specified strings matches the left-hand
@@ -162,7 +162,8 @@ FULL_PATH_NAMES = NO
# will be relative from the directory where doxygen is started.
# This tag requires that the tag FULL_PATH_NAMES is set to YES.
-STRIP_FROM_PATH =
+STRIP_FROM_PATH = @SimMedTK_SOURCE_DIR@ \
+ @SimMedTK_BINARY_DIR@
# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
# path mentioned in the documentation of a class, which tells the reader which
@@ -226,7 +227,7 @@ SEPARATE_MEMBER_PAGES = NO
# uses this value to replace tabs by spaces in code fragments.
# Minimum value: 1, maximum value: 16, default value: 4.
-TAB_SIZE = 4
+TAB_SIZE = 2
# This tag can be used to specify a number of aliases that act as commands in
# the documentation. An alias has the form:
@@ -763,7 +764,11 @@ WARN_LOGFILE =
# spaces.
# Note: If this tag is empty the current directory is searched.
-INPUT = ../
+INPUT = \
+ "@SimMedTK_SOURCE_DIR@/include" \
+ "@SimMedTK_SOURCE_DIR@/src" \
+ "@SimMedTK_BINARY_DIR@/include" \
+ "@SimMedTK_BINARY_DIR@/src"
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1985,7 +1990,7 @@ ENABLE_PREPROCESSING = YES
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-MACRO_EXPANSION = NO
+MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2007,7 +2012,7 @@ SEARCH_INCLUDES = YES
# preprocessor.
# This tag requires that the tag SEARCH_INCLUDES is set to YES.
-INCLUDE_PATH =
+INCLUDE_PATH =
# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
# patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -2069,7 +2074,7 @@ TAGFILES =
# tag file that is based on the input files it reads. See section "Linking to
# external documentation" for more information about the usage of tag files.
-GENERATE_TAGFILE =
+GENERATE_TAGFILE = "@SimMedTK_BINARY_DIR@/documentation/reference/SimMedTK.tags"
# If the ALLEXTERNALS tag is set to YES all external class will be listed in the
# class index. If set to NO only the inherited external classes will be listed.
diff --git a/documentation/conf.py b/documentation/conf.py
new file mode 100644
index 000000000..3759fd431
--- /dev/null
+++ b/documentation/conf.py
@@ -0,0 +1,457 @@
+# -*- coding: utf-8 -*-
+#
+# SimMedTK documentation build configuration file, created by
+# copying SMTK's conf file, which was in turn created by
+# sphinx-quickstart on Thu Sep 18 18:53:31 2014.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+
+readTheDocs = os.environ.get('READTHEDOCS', None) == 'True'
+sys.path.append(os.getcwd()) # So that the findfigure package can be imported
+sourcedir = sys.argv[-2] # FIXME: Is the penultimate argument always the source dir?
+builddir = sys.argv[-1] # FIXME: Is the final argument always be the build dir?
+
+def setup(app):
+ app.add_stylesheet("theme-overrides.css") # prevent stupid-wide table columns.
+
+def runDoxygen(rtdsrcdir, rtdblddir, doxyfileIn, doxyfileOut):
+ """Run Doxygen as part of generating user documentation.
+
+ This is only meant to be used on readthedocs.org to generate
+ reference documentation for linking into the user's guide and
+ tutorial. It should eventually be replaced by something that
+ fetches tag files, XML files, and references remotely-generated
+ documentation from an actual SimMedTK build.
+ """
+ import re
+ import subprocess
+ dxiname = open(os.path.join(rtdsrcdir, doxyfileIn), 'r')
+ cfg = dxiname.read()
+ orgdir = os.path.abspath(os.getcwd())
+ srcdir = os.path.abspath(os.path.join(os.getcwd(), '..'))
+ bindir = srcdir
+ refdir = os.path.abspath(os.path.join(rtdblddir, 'doc', 'reference'))
+ cfg2 = re.sub('@SimMedTK_SOURCE_DIR@', srcdir, \
+ re.sub('@SimMedTK_BINARY_DIR@', os.path.abspath(rtdblddir), cfg))
+ try:
+ os.makedirs(refdir)
+ except OSError as e:
+ if 'File exists' in e:
+ pass
+ except:
+ print 'Failed to create doxygen reference directory %s' % refdir
+ return
+ dxoname = os.path.abspath(os.path.join(refdir, doxyfileOut))
+ dxo = open(dxoname, 'w')
+ print >>dxo, cfg2
+ dxo.close()
+ os.chdir(refdir)
+ print 'Running Doxygen on %s' % dxoname
+ rcode = subprocess.call(('doxygen', dxoname))
+ print ' Doxygen returned %s' % rcode
+ os.chdir(orgdir)
+
+if readTheDocs:
+ """Run Doxygen ourselves"""
+ # Run doxygen ourselves on ReadTheDocs.org so that doxylinks will work.
+ runDoxygen(sourcedir, builddir, 'sparsehash.doxyfile.in', 'sparsehash.doxyfile')
+ runDoxygen(sourcedir, builddir, 'cjson.doxyfile.in', 'cjson.doxyfile')
+ runDoxygen(sourcedir, builddir, 'SimMedTK.doxyfile.in', 'SimMedTK.doxyfile')
+
+# 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.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.coverage',
+ 'sphinx.ext.mathjax',
+ 'sphinx.ext.ifconfig',
+ 'sphinx.ext.todo',
+ 'sphinxcontrib.actdiag',
+ 'sphinxcontrib.doxylink',
+ 'findfigure',
+ 'breathe'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'SimMedTK'
+copyright = u'2015, Kitware, Inc.'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+
+# We exclude files (from being reported as unreferenced) that are explicitly included.
+# We explicitly include files that we want to appear as introductory text above a
+# table of contents listing.
+exclude_patterns = ['userguide-overview.rst']
+
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# -- Findfigure configuration ---------------------------------------------
+
+findfigure_paths = {
+ '*':[
+ sourcedir,
+ os.path.join(sourcedir, 'userguide', 'figures'),
+ builddir,
+ os.path.join(builddir,'..')]
+}
+
+# -- Action diagram configuration -----------------------------------------
+
+actdiag_antialias = True
+
+actdiag_html_image_format = 'SVG'
+actdiag_latex_image_format = 'PDF'
+
+# -- To-do list configuration ---------------------------------------------
+
+# When True, ..todo:: and ..todolist:: produce output, else they produce
+# nothing. The default is False.
+todo_include_todos = True
+
+# -- Doxylink configuration -----------------------------------------------
+
+# The doxylink environment is set up with a dictionary mapping
+# the interpereted text role to a tuple of tag file and prefix:
+tagbase = os.path.join(builddir, '..', '..', 'reference')
+refbase = os.path.join('..', '..', 'reference')
+if readTheDocs:
+ # We store the reference documentation inside the user-doc build
+ # directory on readthedocs so that it will get installed properly.
+ tagbase = os.path.abspath(os.path.join(builddir, 'doc', 'reference'))
+ refbase = os.path.join('doc', 'reference')
+doxylink = {
+ 'sm' : (
+ os.path.join(tagbase, 'SimMedTK.tags'),
+ os.path.join(refbase, 'SimMedTK', 'html'))
+}
+
+# A boolean that decides whether parentheses are appended to
+# function and method role text. Default is True.
+# add_function_parentheses = True
+
+
+# -- Breath configuration -------------------------------------------------
+
+breathe_projects = {
+ 'sm':os.path.join(builddir, '..', '..', 'reference', 'SimMedTK', 'xml') + os.path.sep,
+}
+breathe_default_project = 'SimMedTK'
+breathe_default_members = ['members', 'protected-members', 'undoc-members']
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+if readTheDocs:
+ html_theme = 'default'
+else:
+ try:
+ import sphinx_rtd_theme
+ html_theme = 'sphinx_rtd_theme'
+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+ except:
+ html_theme = 'haiku'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+html_title = u'SimMedTK: Simulations for Medicine Tool Kit'
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# 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']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'SimMedTKdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ ('index', 'SimMedTK.tex', u'SimMedTK Documentation',
+ u'Kitware, Inc.', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'SimMedTK', u'SimMedTK Documentation',
+ [u'Kitware, Inc.'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ ('index', 'SimMedTK', u'SimMedTK Documentation',
+ u'Kitware, Inc.', 'SimMedTK', 'Simulations for medical applications.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+# -- Options for Epub output ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'SimMedTK: Simulations for Medicine Tool Kit'
+epub_author = u'Kitware, Inc.'
+epub_publisher = u'Kitware, Inc.'
+epub_copyright = u'2015, Kitware, Inc.'
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = u'SimMedTK'
+
+# The HTML theme for the epub output. Since the default themes are not optimized
+# for small screen space, using the same theme for HTML and epub output is
+# usually not wise. This defaults to 'epub', a theme designed to save visual
+# space.
+#epub_theme = 'epub'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the PIL.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True
diff --git a/documentation/findfigure.py b/documentation/findfigure.py
new file mode 100644
index 000000000..cd300566a
--- /dev/null
+++ b/documentation/findfigure.py
@@ -0,0 +1,205 @@
+"""
+ The findfigure Sphinx extension allows projects to
+ specify a set of search paths that images may appear in.
+ It is configured by two variables you can set in your
+ project's conf.py file:
+
+ findfigure_paths is a dictionary mapping builder
+ names to a tuple of paths to search.
+
+ findfigure_types is a dictionary mapping builder
+ names to a tuple of figure filename extensions,
+ in descending order of preference.
+
+ See setup() below for more information.
+"""
+
+import os
+import sys
+from docutils import nodes, utils
+from docutils.parsers.rst import directives, states
+from docutils.parsers.rst.directives.images import Image, Figure
+import sphinx.builders
+
+class FindImageDirective(Image):
+ """A directive that finds images in a search path."""
+ def run(self):
+ """Process a new image."""
+ #farfle = open('/tmp/farfle', 'a')
+ env = self.state.document.settings.env
+ reference = directives.uri(self.arguments[0])
+ if not os.path.isabs(reference):
+ # A relative path means we should search for the image
+ # Find the builder-specific path-list to search:
+ bname = env.app.builder.name
+ if bname in sphinx.builders.BUILTIN_BUILDERS:
+ bname = sphinx.builders.BUILTIN_BUILDERS[bname][0] # Get a simplified name (htmlhelp->html, etc)
+
+ if bname in env.app.config.findfigure_paths:
+ searchdirs = env.app.config.findfigure_paths[bname]
+ elif '*' in env.app.config.findfigure_paths:
+ searchdirs = env.app.config.findfigure_paths['*']
+ else:
+ searchdirs = (os.path.abspath('.'),)
+ if reference.endswith('.*'):
+ # Find the builder-specific list of extensions to try
+ base, dummy = os.path.splitext(reference)
+ if bname in env.app.config.findfigure_types:
+ searchexts = env.app.config.findfigure_types[bname]
+ elif '*' in env.app.config.findfigure_types:
+ searchexts = env.app.config.findfigure_types['*']
+ else:
+ searchexts = ('.svg', '.pdf', '.png', '.jpeg', '.jpg', '.tiff', '.tif', '.gif')
+ else:
+ base = reference
+ searchexts = ('',)
+ # Now try finding the figure.
+ foundit = False
+ aref = base
+ for ext in searchexts:
+ for path in searchdirs:
+ try:
+ aref = os.path.join(path, base) + ext
+ #print ' TRY <%s>' % aref
+ status = os.stat(aref) # Could check status bits here.
+ foundit = True
+ break
+ except:
+ foundit = False
+ if foundit:
+ break
+ #print >>farfle, "Reference is %s aref %s found %s" % (self.arguments, aref, foundit)
+ if not foundit:
+ #print 'MISSING FILE %s' % reference
+ return []
+ #print 'RESOLVED %s to %s' % (reference, aref)
+ rewr = os.path.relpath(aref, os.path.join(env.srcdir, os.path.dirname(env.docname)))
+ # NB: We must rewrite path relative to source directory
+ # because otherwise the output stage will be unable
+ # to find it.
+ #print 'REWROTE %s to %s' % (aref, rewr)
+ self.arguments[0] = rewr
+ #farfle.close()
+ return Image.run(self)
+
+class FindFigureDirective(Figure):
+ """A directive that finds figure images in a search path."""
+ def run(self):
+ """Process a new figure."""
+ #farfle = open('/tmp/farfle', 'a')
+ env = self.state.document.settings.env
+ reference = directives.uri(self.arguments[0])
+ if not os.path.isabs(reference):
+ # A relative path means we should search for the image
+ # Find the builder-specific path-list to search:
+ bname = env.app.builder.name
+ if bname in sphinx.builders.BUILTIN_BUILDERS:
+ bname = sphinx.builders.BUILTIN_BUILDERS[bname][0] # Get a simplified name (htmlhelp->html, etc)
+
+ if bname in env.app.config.findfigure_paths:
+ searchdirs = env.app.config.findfigure_paths[bname]
+ elif '*' in env.app.config.findfigure_paths:
+ searchdirs = env.app.config.findfigure_paths['*']
+ else:
+ searchdirs = (os.path.abspath('.'),)
+ if reference.endswith('.*'):
+ # Find the builder-specific list of extensions to try
+ base, dummy = os.path.splitext(reference)
+ if bname in env.app.config.findfigure_types:
+ searchexts = env.app.config.findfigure_types[bname]
+ elif '*' in env.app.config.findfigure_types:
+ searchexts = env.app.config.findfigure_types['*']
+ else:
+ searchexts = ('.svg', '.pdf', '.png', '.jpeg', '.jpg', '.tiff', '.tif', '.gif')
+ else:
+ base = reference
+ searchexts = ('',)
+ # Now try finding the figure.
+ foundit = False
+ aref = base
+ for ext in searchexts:
+ for path in searchdirs:
+ try:
+ aref = os.path.join(path, base) + ext
+ #print ' TRY <%s>' % aref
+ status = os.stat(aref) # Could check status bits here.
+ foundit = True
+ break
+ except:
+ foundit = False
+ if foundit:
+ break
+ #print >>farfle, "Reference is %s aref %s found %s" % (self.arguments, aref, foundit)
+ if not foundit:
+ #print 'MISSING FILE %s' % reference
+ return []
+ #print 'RESOLVED %s to %s' % (reference, aref)
+ rewr = os.path.relpath(aref, os.path.join(env.srcdir, os.path.dirname(env.docname)))
+ # NB: We must rewrite path relative to source directory
+ # because otherwise the output stage will be unable
+ # to find it.
+ #print 'REWROTE %s to %s rel %s' % (aref, rewr, os.path.abspath(os.path.dirname(env.docname)))
+ self.arguments[0] = rewr
+ #farfle.close()
+ return Figure.run(self)
+
+
+def setup(app):
+ """Read configuration for the module.
+
+ This is mainly a list of paths to search and
+ a dictionary of file extension preferences
+ for each builder.
+
+ findfigure_paths is a dictionary mapping builder
+ names to a tuple of paths to search.
+
+ findfigure_types is a dictionary mapping builder
+ names to a tuple of figure filename extensions,
+ in descending order of preference.
+
+ Both settings above take the usual builder names
+ (e.g., "html", "epub") as well as the special
+ name "*", which is used as a fallback when the
+ builder specified is not in the dictionary.
+
+ Thus you may put figures for different builders into
+ different search paths or you may simply use different
+ files types for figures, but place them all in the same
+ search paths (by only providing search paths for "*").
+
+ By default the current directory is searched.
+ The default figure extensions are different
+ for each builder.
+
+ An example is
+
+ findfigure_paths = {
+ '*': (
+ '@CMAKE_CURRENT_SOURCE_DIR@',
+ '@CMAKE_CURRENT_BINARY_DIR@')
+ }
+ findfigure_types = {
+ 'html': ('.svg','.png','.jpeg','.jpg', '.gif'),
+ 'epub': ('.svg','.png','.jpeg','.jpg', '.gif'),
+ 'latex':('.pdf','.png','.jpeg','.jpg')
+ }, 'env')
+
+ This example uses the same set of search paths for
+ all builders but has the HTML and epub builders prefer
+ SVG files over raster images while the LaTeX builder
+ prefers PDF figures over raster images.
+ """
+ defaultpath = os.path.abspath('.')
+ app.add_config_value('findfigure_paths',
+ {
+ '*':(defaultpath,)
+ }, 'env')
+ app.add_config_value('findfigure_types',
+ {
+ 'html': ('.svg','.png','.jpeg','.jpg', '.tiff', '.tif', '.gif'),
+ 'epub': ('.svg','.png','.jpeg','.jpg', '.tiff', '.tif', '.gif'),
+ 'latex':('.pdf','.png','.jpeg','.jpg', '.tiff', '.tif')
+ }, 'env')
+ app.add_directive('findimage',FindImageDirective)
+ app.add_directive('findfigure',FindFigureDirective)
diff --git a/documentation/index.rst b/documentation/index.rst
new file mode 100644
index 000000000..3b9de2e0a
--- /dev/null
+++ b/documentation/index.rst
@@ -0,0 +1,26 @@
+###########################################
+SimMedTK: Simulations for Medicine Tool Kit
+###########################################
+
+.. highlight:: c++
+
+.. role:: cxx(code)
+ :language: c++
+
+.. findimage:: SimMedTK-logo.*
+
+Contents:
+
+.. toctree::
+ :maxdepth: 4
+
+ userguide/index.rst
+
+
+##################
+Indices and tables
+##################
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/documentation/requirements/dev.txt b/documentation/requirements/dev.txt
new file mode 100644
index 000000000..58967a500
--- /dev/null
+++ b/documentation/requirements/dev.txt
@@ -0,0 +1,8 @@
+Pygments==1.6
+Sphinx==1.2.2
+actdiag==0.5.3
+blockdiag==1.4.4
+sphinxcontrib-actdiag==0.7.2
+sphinxcontrib-doxylink==1.3
+sphinx_rtd_theme==0.1.6
+breathe==3.1.0
diff --git a/documentation/userguide/administration.rst b/documentation/userguide/administration.rst
new file mode 100644
index 000000000..717c9f54f
--- /dev/null
+++ b/documentation/userguide/administration.rst
@@ -0,0 +1,116 @@
+.. role:: cxx(code)
+ :language: c++
+
+.. role:: arg(code)
+ :language: sh
+
+.. _smtk-administration:
+
+**********************
+Administering SimMedTK
+**********************
+
+Previous sections covered the concepts and tools for using SimMedTK.
+This section is for system administrators who wish to make SimMedTK
+available to users
+
+* via command-line utilities for end users of SimMedTK, and/or
+* as a library for people developing SimMedTK-based applications.
+
+End-user tool installation
+==========================
+
+This type of installation should be as simple as downloading a
+binary package of SimMedTK and clicking install.
+
+.. todo:: Expand on details of installation and configuration.
+
+Developer installation
+======================
+
+In addition to the binary installer, there should also be a development
+package that contains header and configuration files needed to build
+C++ applications using SimMedTK. Install this the same way you installed
+the binary above.
+
+You can also download the source code from the git repostory and
+follow the instructions for building and installing SimMedTK in the
+toplevel :file:`ReadMe.mkd` file.
+
+.. todo:: Expand on details of installation and configuration.
+
+Configuration of SimMedTK
+=========================
+
+Some components of SimMedTK will not be available unless
+they are properly configured.
+One example is access to haptic or virtual reality display
+devices.
+
+.. todo::
+
+ Expand on details of configuration here, especially things only
+ sysadmins would need to customize as opposed to end users.
+
+Search paths
+------------
+
+.. todo::
+
+ Explain how SimMedTK searches for simulation inputs.
+
+The default locations that SimMedTK searches for these
+worker files varies by operating system:
+
+Linux
+ SimMedTK searches the current working directory of the
+ process, followed by the :file:`var/simmedtk` subdirectory
+ of the toplevel installation directory.
+ For example, if SimMedTK is installed into :file:`/usr`
+ then it will search :file:`/usr/var/simmedtk`.
+
+ If the :cxx:`SimMedTK_CONFIG_DIR` environment variable is set
+ to a valid path, then it is searched as well.
+
+Mac OS X
+ SimMedTK searches the current working directory of the
+ process, followed by the :file:`var/simmedtk` subdirectory
+ of the toplevel installation directory if SimMedTK is not part of a bundle.
+ For example, if SimMedTK is installed into :file:`/usr`
+ then it will search :file:`/usr/var/simmedtk/workers`.
+
+ If an application built with SimMedTK is part of a bundle (such as an app),
+ then SimMedTK will search the :file:`Contents/Resources` directory
+ of the bundle.
+
+ If the :cxx:`SimMedTK_CONFIG_DIR` environment variable is set
+ to a valid path, then it is searched as well.
+
+Windows
+ SimMedTK searches the current working directory of the process
+ followed by the directory containing the process executable
+ (when provided to SimMedTK by the application).
+
+ If the :cxx:`SimMedTK_CONFIG_DIR` environment variable is set
+ to a valid path, then it is searched as well.
+
+Creating simulation scenes
+--------------------------
+
+Other portions of this manual have covered how to create a
+custom simulation by writing C++ code.
+However, in some cases, it is sufficient to just create new
+or adapt existing configuration files and use the simulation
+program that comes with SimMedTK.
+
+The simulation program that comes with SimMedTK is a
+command-line utility named :file:`vegaFemExample`.
+You can run
+
+.. code:: sh
+
+ vegaFemExample -help
+
+to obtain reference information on the command-line arguments.
+
+.. todo:: Describe changing input decks in more detail and verify the notes above.
diff --git a/documentation/userguide/contributing.rst b/documentation/userguide/contributing.rst
new file mode 100644
index 000000000..9b328f4bf
--- /dev/null
+++ b/documentation/userguide/contributing.rst
@@ -0,0 +1,161 @@
+********************
+Contributing to SimMedTK
+********************
+
+.. role:: cxx(code)
+ :language: c++
+
+.. contents::
+
+The first step to contributing to SimMedTK is to obtain the source code and build it.
+The top-level ReadMe.mkd file in the source code includes instructions for building SimMedTK.
+The rest of this section discusses how the source and documentation are organized
+and provides guidelines for how to match the SimMedTK style.
+
+Source code organization
+========================
+
+SimMedTK currently keeps its header and implementation files in parallel directory structures.
+Implementation files live in :file:`src` while header files live in :file:`include`.
+Inside each of these directories are a number of subdirectories corresponding to
+libraries that encapsulate difference components of SimMedTK.
+With that in mind:
+
+* include — this directory contains all of the header files for SimMedTK libraries
+* src — this directory contains all of the source code for SimMedTK libraries and unit tests
+
+ * smCore — a library for classes used throughout SimMedTK
+ * smRendering — source for :ref:`sm-rendering-sys` rendering code
+
+* examples — demonstration applications that use SimMedTK libraries
+* documentation — user's guide documentation and configuration for the in-source documentation
+* CMake — scripts to aid in configuring, installing, and packaging SimMedTK
+
+
+Inside some :file:`src/`, subdirectories, there are :file:`UnitTests/` directories that
+contain Bandit_-based unit tests.
+
+.. _Bandit: http://banditcpp.org/
+
+Code style
+==========
+
+* No tabs or trailing whitespace are allowed.
+* Indent blocks by 2 spaces.
+* Class names should be camel case, starting with an uppercase.
+* Class member variables should start with :cxx:`m_` or :cxx:`s_` for per-instance or class-static variables, respectively.
+* Class methods should be camel case starting with a lowercase character (except acronyms which should be all-uppercase).
+* Use shared pointers and a static :cxx:`create()` method for classes that own significant storage or must be passed by
+ reference to their superclass.
+
+Using SimMedTK from another project
+===================================
+
+.. todo::
+
+ SimMedTK does not currently export an SimMedTKConfig.cmake file like it should.
+
+Extending SimMedTK
+==================
+
+See the tutorials for in-depth guides on how to extend SimMedTK
+in certain obvious directions,
+
+* Writing an attribute system template file to represent a solver's input format.
+* Writing an exporter to support a new solver's input format.
+* Adding a new solid-modeling operator
+* Bridging SimMedTK to a new solid-modeling kernel
+
+Documentation style
+===================
+
+There are two types of documentation in SimMedTK:
+Doxygen_ documentation written as comments in C++ code and
+Sphinx_ documentation written in reStructuredText_ files (and optionally Python documentation strings).
+The former is used to create reference documentation; the latter is used for the user's guide and tutorials.
+
+The following rules apply to writing documentation:
+
+* Header files should contain the Doxygen documentation for the class as a whole plus any enums declared outside classes, however:
+* Implementation files should contain the Doxygen documentation for class methods.
+ This keeps the documentation next to the implementation (making it easier to keep up-to-date).
+ It also makes the headers easier to read.
+* If a class provides high-level functionality, consider writing some user-guide-style documentation
+ in the User's Guide (in :file:`doc/userguide.rst`) or a tutorial (in :file:`doc/tutorials/`).
+ Tutorials should include a working example that is run as a CTest test.
+ The code in the example should be referenced indirectly by the tutorial so that
+ the the exact code that is tested appears as the text of the tutorial.
+* In reStructuredText documents, you should use the doxylinks_ module to link to
+ the Doxygen documentation *when appropriate*.
+ Examples:
+ ``:sm:`smCoreClass``` produces this link: :sm:`smCoreClass` while the
+ ``:sm:`CoreClass <smCoreClass>``` variant can produce
+ links (:sm:`CoreClass <smCoreClass>` in this case) whose text varies from the classname
+ or whose classnames are ambiguous because of namespaces.
+ The leading ``:sm:`` names the tag file holding the class and function definitions;
+ other third-party-library tag files may be added in the future.
+
+ You will be tempted to make every word that is a classname into a Doxygen link; do not do this.
+ Instead, provide a Doxygen link at the first occurrence of the classname in a topic's
+ discussion — or at most in a few key places. Otherwise the documentation becomes difficult to read
+ due to conflicting text styles.
+* In reStructuredText, when you wish to show code in-line but it is inappropriate to link to Doxygen documentation,
+ use the ``:cxx:`` role for C++ (e.g., :cxx:`if (foo)`), the ``:file:`` role for paths to files (e.g., :file:`doc/index.rst`), and so on.
+ See the `documentation for roles in reStructuredText`_ for more information.
+* Note that the user's guide and tutorials are both included in the top-level :file:`doc/index.rst` file
+ parsed by Sphinx.
+ Several extensions to Sphinx are used and these are configured in :file:`doc/conf.py`.
+
+To get started documenting your code, you should at least have doxygen_ and graphviz_ installed.
+These are available using Homebrew_ on Mac OS X, your Linux distribution's package manager, or by binary
+installer from the source maintainer on Windows.
+
+Additionally there are a number of Python packages that provide Sphinx, docutils, and other packages required
+to generate the user's guide.
+These packages can all be installed with pip:
+
+.. highlight:: sh
+.. code-block:: sh
+
+ # The basic utilities for processing the user's guide:
+ sudo pip install docutils
+ sudo pip install Sphinx
+ # For linking to external Doxygen docs:
+ sudo pip install sphinxcontrib-doxylink
+ # For creating inline class docs from Doxygen XML:
+ sudo pip install breathe
+ # For the default theme:
+ sudo pip install sphinx-rtd-theme
+ # For syntax highlighting:
+ sudo pip install Pygments
+ # For activity diagrams:
+ sudo pip install sphinxcontrib-actdiag
+
+If you are unfamiliar with the documentation packages here, see these links for examples of their use
+(or use SimMedTK by example):
+
+* `Sphinx Table of Contents <http://sphinx-doc.org/contents.html>`_
+* `Sphinx conf.py configuration <http://sphinx-doc.org/config.html>`_
+* `reStructuredText primer <http://sphinx-doc.org/rest.html>`_
+* `Doxygen commands <http://www.stack.nl/~dimitri/doxygen/manual/index.html>`_
+
+
+.. _doxygen: http://doxygen.org/
+.. _doxylinks: https://pypi.python.org/pypi/sphinxcontrib-doxylink
+.. _graphviz: http://graphviz.org/
+.. _Homebrew: http://brew.sh/
+.. _Sphinx: http://sphinx-doc.org/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _VTK: http://vtk.org/
+.. _documentation for roles in reStructuredText: http://sphinx-doc.org/markup/inline.html
+
+To-do list
+==========
+
+Finally, if you are looking for a way to contribute,
+helping with the documentation would be great.
+A list of incomplete documentation (or incomplete features)
+is below.
+You can also look on the SimMedTK issue tracker for things to do.
+
+.. todolist::
diff --git a/documentation/userguide/figures/SimMedTK-logo.svg b/documentation/userguide/figures/SimMedTK-logo.svg
new file mode 100644
index 000000000..51416905b
--- /dev/null
+++ b/documentation/userguide/figures/SimMedTK-logo.svg
@@ -0,0 +1,284 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="768.46692"
+ height="164.19327"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.91 r13725"
+ sodipodi:docname="SimMedTK-logo.svg">
+ <defs
+ id="defs4">
+ <linearGradient
+ inkscape:collect="always"
+ id="linearGradient4485">
+ <stop
+ style="stop-color:#787878;stop-opacity:1"
+ offset="0"
+ id="stop4487" />
+ <stop
+ id="stop4493"
+ offset="0.23576376"
+ style="stop-color:#747474;stop-opacity:0.76078433" />
+ <stop
+ style="stop-color:#595959;stop-opacity:0.627451"
+ offset="0.36731616"
+ id="stop4495" />
+ <stop
+ id="stop4497"
+ offset="0.52120763"
+ style="stop-color:#414141;stop-opacity:0.4745098;" />
+ <stop
+ style="stop-color:#2c2c2c;stop-opacity:0.24705882"
+ offset="0.74708062"
+ id="stop4499" />
+ <stop
+ style="stop-color:#000000;stop-opacity:0"
+ offset="1"
+ id="stop4489" />
+ </linearGradient>
+ <linearGradient
+ inkscape:collect="always"
+ id="linearGradient4460">
+ <stop
+ style="stop-color:#7e7e7e;stop-opacity:1"
+ offset="0"
+ id="stop4462" />
+ <stop
+ id="stop4466"
+ offset="0.33079433"
+ style="stop-color:#898989;stop-opacity:1" />
+ <stop
+ style="stop-color:#848484;stop-opacity:1"
+ offset="0.4912852"
+ id="stop4470" />
+ <stop
+ style="stop-color:#767676;stop-opacity:1"
+ offset="0.70200968"
+ id="stop4468" />
+ <stop
+ style="stop-color:#838383;stop-opacity:1"
+ offset="1"
+ id="stop4464" />
+ </linearGradient>
+ <linearGradient
+ id="linearGradient4430"
+ inkscape:collect="always">
+ <stop
+ id="stop4454"
+ offset="0"
+ style="stop-color:#a1a1a1;stop-opacity:1" />
+ <stop
+ id="stop4456"
+ offset="1"
+ style="stop-color:#f2f2f2;stop-opacity:1" />
+ </linearGradient>
+ <linearGradient
+ inkscape:collect="always"
+ id="linearGradient4418">
+ <stop
+ style="stop-color:#ececec;stop-opacity:1"
+ offset="0"
+ id="stop4420" />
+ <stop
+ id="stop4438"
+ offset="0.21843562"
+ style="stop-color:#b5b5b5;stop-opacity:1" />
+ <stop
+ id="stop4426"
+ offset="0.49246445"
+ style="stop-color:#929292;stop-opacity:1" />
+ <stop
+ style="stop-color:#b3b3b3;stop-opacity:1"
+ offset="0.69688219"
+ id="stop4428" />
+ <stop
+ style="stop-color:#c5c5c5;stop-opacity:1"
+ offset="1"
+ id="stop4422" />
+ </linearGradient>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3879"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ style="overflow:visible"
+ id="Arrow1Mend-2"
+ refX="0"
+ refY="0"
+ orient="auto"
+ inkscape:stockid="Arrow1Mend">
+ <path
+ inkscape:connector-curvature="0"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+ id="path3879-7" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend-2-6"
+ style="overflow:visible">
+ <path
+ id="path3879-7-2"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <marker
+ style="overflow:visible"
+ id="Arrow1Mend-3"
+ refX="0"
+ refY="0"
+ orient="auto"
+ inkscape:stockid="Arrow1Mend">
+ <path
+ transform="matrix(-0.4,0,0,-0.4,-4,0)"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
+ d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+ id="path3879-0"
+ inkscape:connector-curvature="0" />
+ </marker>
+ <linearGradient
+ inkscape:collect="always"
+ xlink:href="#linearGradient4418"
+ id="linearGradient4424"
+ x1="14.260432"
+ y1="137.29317"
+ x2="734.13086"
+ y2="62.541885"
+ gradientUnits="userSpaceOnUse" />
+ <radialGradient
+ inkscape:collect="always"
+ xlink:href="#linearGradient4430"
+ id="radialGradient4436"
+ cx="152.10765"
+ cy="246.97377"
+ fx="152.10765"
+ fy="246.97377"
+ r="235.38449"
+ gradientTransform="matrix(0.9869954,-0.24147399,0.08181502,0.33440886,-16.248799,95.227372)"
+ gradientUnits="userSpaceOnUse" />
+ <linearGradient
+ inkscape:collect="always"
+ xlink:href="#linearGradient4460"
+ id="linearGradient4476"
+ gradientUnits="userSpaceOnUse"
+ x1="152.71005"
+ y1="133.16454"
+ x2="443.68704"
+ y2="115.66454" />
+ <linearGradient
+ inkscape:collect="always"
+ xlink:href="#linearGradient4485"
+ id="linearGradient4491"
+ x1="172.51085"
+ y1="109.18848"
+ x2="460.2832"
+ y2="109.18848"
+ gradientUnits="userSpaceOnUse" />
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="0.9899495"
+ inkscape:cx="326.00554"
+ inkscape:cy="107.18886"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1631"
+ inkscape:window-height="1140"
+ inkscape:window-x="41"
+ inkscape:window-y="101"
+ inkscape:window-maximized="0"
+ showguides="true"
+ inkscape:guide-bbox="true"
+ fit-margin-top="10"
+ fit-margin-left="10"
+ fit-margin-right="10"
+ fit-margin-bottom="10" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(10.485365,-11.76087)">
+ <path
+ inkscape:connector-curvature="0"
+ style="fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+ d="m 392.26283,22.26087 c -111.78571,0 -333.743196,18.70479 -374.287111,23.57032 -8.3935675,2.24905 -14.661084,7.64877 -17.857422,13.57226 0,0 45.001116,52.14258 76.429688,72.14258 31.428575,20 82.857135,32.1437 99.999995,33.57227 17.14286,1.42857 79.88365,-2.14314 113.45508,-2.85743 33.57143,-0.71428 160.4043,0.87891 160.4043,0.87891 0,0 10.09452,-7.89909 18.07422,-17.2207 21.38524,-14.58902 73.58968,-17.73054 108.0664,-20.08789 40.79883,-2.78964 102.16422,7.82253 142.38086,18.15429 L 747.26283,131.54603 686.54798,29.40345 c 0,0 -182.49944,-7.14258 -294.28515,-7.14258 z m 226.25585,30.10352 c 9.59646,0 11.36427,12.12328 12.62696,22.98242 1.26269,10.85914 -4.03969,20.4545 -16.41406,20.70703 -12.37437,0.25254 -147.48243,5.30274 -147.48243,5.30274 l -14.64648,-8.33203 c 0,0 -125.2606,0.25195 -138.39258,0.25195 -3.54454,0 -8.08008,-4.04065 -8.08008,-10.10156 0,-3.283 0.25196,-3.44396 0.25196,-6.56641 0,-5.42436 5.30411,-9.0918 8.08203,-9.0918 l 27.27344,0 7.57617,-5.30273 103.28906,0.25195 12.62695,-9.34375 c 0,0 143.69261,-0.75781 153.28906,-0.75781 z"
+ id="path4300" />
+ <g
+ id="g14573"
+ transform="translate(0,-40)" />
+ <path
+ id="path4295"
+ d="m 392.26283,22.26087 c -111.78571,0 -333.743196,18.70479 -374.287111,23.57032 -8.3935675,2.24905 -14.661084,7.64877 -17.857422,13.57226 0,0 45.001116,52.14258 76.429688,72.14258 31.428575,20 82.857135,32.1437 99.999995,33.57227 17.14286,1.42857 79.88365,-2.14314 113.45508,-2.85743 33.57143,-0.71428 160.4043,0.87891 160.4043,0.87891 0,0 10.09452,-7.89909 18.07422,-17.2207 21.38524,-14.58902 73.58968,-17.73054 108.0664,-20.08789 40.79883,-2.78964 102.16422,7.82253 142.38086,18.15429 L 747.26283,131.54603 686.54798,29.40345 c 0,0 -182.49944,-7.14258 -294.28515,-7.14258 z m 226.25585,30.10352 c 9.59646,0 11.36427,12.12328 12.62696,22.98242 1.26269,10.85914 -4.03969,20.4545 -16.41406,20.70703 -12.37437,0.25254 -147.48243,5.30274 -147.48243,5.30274 l -14.64648,-8.33203 c 0,0 -125.2606,0.25195 -138.39258,0.25195 -3.54454,0 -8.08008,-4.04065 -8.08008,-10.10156 0,-3.283 0.25196,-3.44396 0.25196,-6.56641 0,-5.42436 5.30411,-9.0918 8.08203,-9.0918 l 27.27344,0 7.57617,-5.30273 103.28906,0.25195 12.62695,-9.34375 c 0,0 143.69261,-0.75781 153.28906,-0.75781 z"
+ style="fill:url(#linearGradient4424);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ inkscape:connector-curvature="0" />
+ <path
+ style="fill:url(#radialGradient4436);fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="M 17.081188,46.094859 C 9.1396997,48.478664 3.199267,53.693761 0.118297,59.403453 c 0,-10e-7 45.001116,52.142577 76.429688,72.142577 31.428575,20 82.857135,32.1437 99.999995,33.57227 17.14286,1.42857 79.88365,-2.14314 113.45508,-2.85743 33.57143,-0.71428 160.4043,0.87891 160.4043,0.87891 0,0 10.09452,-7.89909 18.07422,-17.2207 0.0529,-0.0361 0.11269,-0.0695 0.16601,-0.10547 -63.50684,0.0208 -259.88492,0.1476 -289.29297,1 -11.4323,0.33137 -23.89729,-2.10904 -36.37866,-6.09109 C 117.40907,132.56568 91.773383,117.94019 74.803844,107.41908 49.550027,91.76172 26.317092,60.445979 17.225719,46.303843 c -0.04489,-0.06983 -0.09741,-0.139277 -0.144531,-0.208984 z"
+ id="path4290"
+ inkscape:connector-curvature="0"
+ sodipodi:nodetypes="ccssscccssssc" />
+ <text
+ transform="matrix(1,0,0.07992674,1,0,0)"
+ sodipodi:linespacing="125%"
+ id="text4472"
+ y="141.08685"
+ x="296.26447"
+ style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.85363245px;line-height:125%;font-family:Sans;-inkscape-font-specification:'Sans, Normal';text-align:center;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:url(#linearGradient4476);fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ xml:space="preserve"><tspan
+ style="font-style:normal;font-variant:normal;font-weight:300;font-stretch:normal;font-size:54.8290596px;line-height:125%;font-family:'Hiragino Kaku Gothic Pro';-inkscape-font-specification:'Hiragino Kaku Gothic Pro, Light';text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:url(#linearGradient4476);fill-opacity:1;stroke:none;stroke-opacity:1"
+ y="141.08685"
+ x="296.26447"
+ id="tspan4474"
+ sodipodi:role="line">SimMedTK</tspan></text>
+ <path
+ style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.85363245px;line-height:125%;font-family:Sans;-inkscape-font-specification:'Sans, Normal';text-align:center;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:url(#linearGradient4491);fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 183.68164,88.613281 c -3.93143,0 -7.14127,0.962552 -9.41406,2.667969 -1.30662,1.802054 -1.92608,4.063287 -1.7168,6.681641 0.30676,3.838029 2.24019,6.745049 5.79297,8.664059 1.94745,1.04176 4.147,1.80871 7.6582,2.52149 6.75264,1.48038 7.3691,1.64575 9.26172,2.6875 2.17553,1.15141 3.43371,3.18056 3.64844,5.86718 0.22992,2.87659 -0.84907,5.1056 -3.00391,6.50391 -1.49036,2.34119 -4.54338,3.66406 -8.8164,3.66406 -4.05735,0 -7.45485,-1.37072 -9.45703,-3.7832 -1.26974,-1.48038 -1.75993,-2.79594 -2.13477,-5.42773 l -2.2793,0.29101 c 0.68493,2.47546 1.41309,3.97101 2.71289,5.55078 2.79384,3.3994 7.49001,5.20703 13.63086,5.20703 4.29401,0 7.65075,-0.91824 9.98828,-2.63867 1.4063,-1.93975 2.0332,-4.4485 1.79102,-7.47851 -0.50835,-6.36017 -4.28343,-9.70417 -13.20508,-11.56836 -6.4149,-1.37073 -6.46946,-1.37149 -7.99805,-1.97461 -3.34008,-1.3159 -5.03774,-3.3442 -5.26562,-6.195314 -0.20068,-2.510789 0.89774,-4.564737 2.91016,-5.876954 1.40531,-2.224644 4.30845,-3.580078 8.08789,-3.580078 3.56389,0 6.44808,1.098137 8.36914,3.181641 1.14254,1.261068 1.66928,2.357619 2.2832,4.550781 l 2.02344,-0.292968 c -0.62093,-1.755918 -1.26151,-2.894777 -2.34766,-4.177735 -2.73024,-3.289743 -7.09145,-5.044922 -12.51953,-5.044922 z m 236.80859,0.330078 c -1.78744,0.274146 -3.25936,0.382813 -6.43945,0.382813 l -21.38281,0 c -1.76707,0 -2.97801,-0.04525 -4.10156,-0.138672 l 0.18945,2.361328 c 1.78745,-0.274145 3.47715,-0.384765 6.27344,-0.384766 l 8.55468,0 2.52735,31.636718 c 0.20597,2.57697 0.24976,4.49561 0.0566,6.19531 l 2.73242,0 c -0.21802,-1.20554 -0.37271,-2.45606 -0.51172,-4.19531 l -2.52929,-31.636718 2.16015,0 -0.16015,-2 8.49804,0 c 1.86135,0 3.16292,0.04781 4.32227,0.140626 l -0.18946,-2.361329 z m -212.49804,0.382813 0.23047,2.880859 3.1582,0 -0.23047,-2.880859 -3.1582,0 z m 64.67383,0 c 0.23504,1.321731 0.40303,2.70126 0.54882,4.52539 l 2.29102,28.675778 c 0.22788,2.85111 0.24691,4.44008 0.0801,6.46875 l 2.56445,0 c -0.21964,-1.23846 -0.38145,-2.59448 -0.53125,-4.46875 l -1.875,-23.46679 c -0.10517,-1.315901 -0.59629,-4.714619 -0.94922,-7.072269 1.30907,3.344573 2.0471,5.044298 3.00977,6.798829 l 0.0918,0.17187 -0.15234,-1.898433 c -0.10517,-1.315898 -0.59629,-4.714616 -0.94922,-7.072266 1.30907,3.344573 2.0471,5.044298 3.00977,6.798828 l 12.97461,24.453121 c 1.29378,2.46731 2.10215,4.33031 2.49023,5.75586 l 2.32227,0 c 0.27704,-1.06305 0.64291,-2.18037 1.19726,-3.70117 l 9.21875,-24.61914 c 0.86208,-2.24799 1.45365,-4.439507 1.82227,-6.687499 -0.0283,1.603577 0.0109,3.410096 0.0742,4.962891 l 0.10351,-0.275391 c 0.86208,-2.247991 1.45365,-4.439508 1.82227,-6.6875 -0.0396,2.247992 0.0316,5.206974 0.1543,6.742188 l 1.90234,23.796871 c 0.21035,2.6318 0.2581,4.60457 0.0781,6.46875 l 2.56836,0 c -0.21916,-1.21675 -0.37702,-2.51476 -0.5332,-4.46875 l -2.29297,-28.675778 c -0.22788,-2.851111 -0.24448,-4.441886 -0.082,-6.52539 l -4.69141,0 c -0.25114,1.036365 -0.5892,2.149474 -1.04492,3.429687 l -11.07422,30.208981 -0.74804,-1.41601 -1.25196,3.41601 -15.95703,-30.208981 c -0.96705,-1.809359 -1.78174,-3.784815 -2.24219,-5.429687 l -3.94921,0 z m 106.5625,0 c 0.21387,1.271586 0.36938,2.544417 0.50586,4.251953 l 0.58789,7.345705 c 0.10079,1.26107 0.13996,1.75484 0.39648,2.90625 l 0.11914,0.82226 c -0.76556,-1.06682 -1.63627,-1.98788 -2.59961,-2.76953 l 0.084,1.04102 c 0.10079,1.26107 0.13996,1.75484 0.39648,2.90625 l 0.11914,0.82226 c -2.71486,-3.7832 -6.71368,-5.81054 -11.70312,-5.81054 -3.04997,0 -5.62382,0.8255 -7.6211,2.33789 -2.03965,2.6581 -3.00742,6.42446 -2.64062,11.01367 0.76252,9.54026 6.38054,15.35156 14.82422,15.35156 3.08069,0 5.55819,-0.73442 7.53515,-2.23633 0.40079,-0.51537 0.77777,-1.07324 1.12305,-1.68554 -0.009,0.23302 -0.004,0.46753 -0.006,0.70312 0.75113,-0.76232 1.41847,-1.66148 2.00586,-2.70312 -0.0352,0.93209 -0.0106,1.91989 0.0508,2.6875 l 0.21289,2.68554 2.00977,0 c -0.2121,-1.25063 -0.36465,-2.48898 -0.50977,-4.30468 L 381.787,95.523438 c -0.19282,-2.412479 -0.21018,-4.004104 -0.11133,-6.197266 l -2.44726,0 z m 48.61523,0 c 0.22409,1.238292 0.37958,2.489367 0.51172,4.142578 l 2.34765,29.38672 c 0.20159,2.52214 0.24148,4.38609 0.0527,6.14062 l 2.67187,0 c -0.21083,-1.16403 -0.36213,-2.39123 -0.50195,-4.14062 l -0.71484,-8.93555 5.91015,-6.30664 0.0606,0.0703 1.93945,-2.07031 14.27344,16.66797 c 1.6886,1.91902 2.73416,3.34412 3.61133,4.71484 l 2.27734,0 c -0.78466,-0.82611 -1.79511,-1.96252 -3.54882,-3.97461 l -15.82422,-18.25976 10.90039,-11.787111 c 0.15134,-0.164487 0.75649,-0.823482 1.66015,-1.865234 0.65143,-0.767607 1.41356,-1.534844 2.22071,-2.412109 0.40357,-0.438633 0.40203,-0.439 1.31445,-1.371094 l -5.70117,0 c -0.534,0.708367 -1.22458,1.504206 -2.1875,2.550781 l -15.32617,16.779297 -0.0137,-0.17383 -1.98632,2.17383 -1.21485,-15.1875 c -0.21473,-2.686624 -0.24147,-4.388048 -0.0527,-6.142578 l -2.67969,0 z m -92.94922,11.404298 c -3.04531,0 -5.62797,0.84643 -7.64062,2.38281 -2.08425,2.70059 -3.08542,6.52283 -2.7168,11.13477 0.75814,9.48542 6.66918,15.51562 15.27734,15.51562 3.32925,0 6.12072,-0.92194 8.33594,-2.67969 0.73854,-0.93941 1.27064,-1.93426 1.93164,-3.70898 l -2.94726,-1.14258 c -0.62097,1.09401 -1.41769,1.96852 -2.38672,2.61914 -1.53686,2.24399 -3.93951,3.4043 -7.16016,3.4043 -3.28974,0 -6.08194,-1.31604 -8.0293,-3.72852 -1.63814,-1.97384 -2.34854,-4.00223 -2.80664,-7.67578 l 2.31446,0 c -0.11693,-0.61485 -0.22301,-1.26671 -0.31446,-2 l 20.74219,0 c -0.14783,-0.84835 -0.32662,-1.90518 -0.38086,-2.22265 -1.68381,-7.3471 -7.1458,-11.89844 -14.21875,-11.89844 z m -100.87695,0.11133 c -2.49476,0 -4.62994,0.61551 -6.26563,1.77734 -0.49547,0.64193 -0.80996,1.16572 -1.10156,1.81445 -0.0123,-0.44926 -0.0162,-0.54506 -0.0215,-0.85156 -0.0364,0.038 -0.0777,0.0707 -0.11329,0.10938 -1.00455,1.15141 -1.44627,1.81009 -1.86523,2.74218 -0.0284,-1.04175 -0.0269,-1.70046 -0.0488,-1.97461 l -0.24023,-3.01562 -2.05664,0 c 0.20121,1.19032 0.35274,2.42812 0.49414,4.19726 l 1.37109,17.16016 c 0.20597,2.57697 0.22967,4.22147 0.11328,6.19531 l 2.46485,0 c -0.21401,-1.26887 -0.38577,-2.52166 -0.51953,-4.19531 l -0.85938,-10.74609 c -0.11394,-1.42556 0.50249,-4.00204 1.37109,-5.48242 0.65472,-1.15695 1.51459,-2.08736 2.50586,-2.78321 1.51794,-2.14687 3.79082,-3.38476 6.34375,-3.38476 3.9477,0 6.35069,2.63207 6.73633,7.45703 l 1.03516,12.93945 c 0.2235,2.79628 0.22771,4.22147 0.11133,6.19531 l 2.54296,0 c -0.19481,-1.1596 -0.3435,-2.40253 -0.48242,-4.14062 l -0.86328,-10.80078 c -0.13147,-1.64487 0.44276,-4.05644 1.35742,-5.64649 0.62262,-1.13097 1.46917,-2.03846 2.45118,-2.71093 1.43499,-2.08206 3.66709,-3.29297 6.13671,-3.29297 4.38633,0 6.48603,2.24827 6.90235,7.45703 l 1.0332,12.93945 c 0.23226,2.90594 0.27816,4.16664 0.11133,6.19531 l 2.54687,0 c -0.19659,-1.16402 -0.3465,-2.39124 -0.48632,-4.14062 l -1.08204,-13.54297 c -0.25855,-3.23491 -0.97746,-5.37242 -2.43359,-7.12695 -1.82016,-2.19317 -4.65472,-3.34375 -8.27344,-3.34375 -2.5565,0 -4.56025,0.54299 -6.22265,1.74609 -0.50768,0.65567 -0.99258,1.38068 -1.44336,2.23047 -0.0978,-0.23663 -0.17972,-0.41586 -0.26758,-0.61524 -0.62056,0.73853 -1.19531,1.60271 -1.73242,2.61524 -0.67976,-1.64487 -1.06057,-2.30438 -1.95313,-3.18164 -1.79387,-1.86419 -4.17162,-2.79492 -7.29687,-2.79492 z m -24.66797,0.60156 c 0.20358,1.21658 0.35823,2.49682 0.49414,4.19726 l 1.37109,17.16016 c 0.18406,2.30282 0.19899,3.83766 0.11328,6.19531 l 2.55665,0 c -0.21505,-1.27296 -0.3678,-2.5168 -0.50196,-4.19531 l -1.37109,-17.16016 c -0.21912,-2.74145 -0.23209,-4.27824 -0.11133,-6.19726 l -2.55078,0 z m 127.71094,0.74219 c 2.63179,0 4.8368,0.82192 6.66797,2.46679 1.89038,1.6997 2.87092,3.67372 3.44531,6.74414 l -2.48438,0 c 0.18781,0.61416 0.34859,1.27414 0.48438,2 l -18.53321,0 c 0.16245,-2.0835 0.35758,-3.07068 1.01563,-4.4414 0.67304,-1.47665 1.64376,-2.62566 2.83594,-3.43164 1.5036,-2.15192 3.79359,-3.33789 6.56836,-3.33789 z m 32.79687,0.21875 c 2.90594,0 5.62144,1.04206 7.68946,2.90625 2.12722,1.91901 3.47834,5.10003 3.76757,8.71875 0.37426,4.68249 -1.06741,8.27545 -3.86328,10.23632 -1.65071,2.32854 -4.29681,3.66016 -7.71289,3.66016 -3.07043,0 -5.74072,-1.15073 -7.61133,-3.28906 -1.57017,-1.80936 -2.64241,-4.93402 -2.93164,-8.55274 -0.39097,-4.89167 0.95966,-8.46726 3.68946,-10.29687 1.48133,-2.17841 3.85407,-3.38281 6.97265,-3.38281 z"
+ transform="translate(-10.485365,11.76087)"
+ id="text4221"
+ inkscape:connector-curvature="0" />
+ </g>
+</svg>
diff --git a/documentation/userguide/index.rst b/documentation/userguide/index.rst
new file mode 100644
index 000000000..906127762
--- /dev/null
+++ b/documentation/userguide/index.rst
@@ -0,0 +1,34 @@
+=====================
+SimMedTK User's Guide
+=====================
+
+The Simulations for Medicine Tool Kit, or SimMedTK, is a framework
+to help you create interactive applications that simulate mechanical
+(and other) aspects of biological systems.
+
+For instructions on obtaining, building, and installing
+SMTK, clone the repository:
+
+.. code:: sh
+
+ git clone https://gitlab.kitware.com/SimMedTK/SimMedTK.git
+
+and follow the instructions in the :file:`ReadMe.mkd` file
+in the top-level source directory.
+The rest of this user's guide assumes you have built
+and installed SMTK according to these instructions.
+
+.. todo::
+
+ Add high-level discussion of the components of the toolkit
+ and how they fit together (before the "administration.rst"
+ line below).
+
+.. toctree::
+ :maxdepth: 4
+
+ administration.rst
+ contributing.rst
+
+.. role:: cxx(code)
+ :language: c++
--
GitLab