enh: directly use config.py for sphinx docs

modify sphinx cmake macro to support both a cmake config'd
(config.py.in) and standard config.py

move to use config.py so we can more easily leverage read the docs

fix a few typos

src/CMake/SetupDocs.cmake

@@ -114,21 +114,35 @@ macro(add_sphinx_target sphinx_target_name )
     # HTML output directory
     set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
 
-    configure_file("${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
-                   "${SPHINX_BUILD_DIR}/conf.py"
-                   @ONLY)
-
-    add_custom_target(${sphinx_target_name}
-            ${SPHINX_EXECUTABLE}
-            -q -b html
-            #-W disable warn on error for now, while our sphinx env is still in flux
-            -c "${SPHINX_BUILD_DIR}"
-            -d "${SPHINX_CACHE_DIR}"
-            "${CMAKE_CURRENT_SOURCE_DIR}"
-            "${SPHINX_HTML_DIR}"
-            COMMENT "Building HTML documentation with Sphinx"
-            DEPENDS ${deps})
+    # support both a cmake config-d sphinx input file (config.py.in)
+    # and direct use of a config.py file.
+    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in")
 
+        configure_file("${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
+                       "${SPHINX_BUILD_DIR}/conf.py"
+                       @ONLY)
+
+        add_custom_target(${sphinx_target_name}
+                          ${SPHINX_EXECUTABLE}
+                          -q -b html
+                          #-W disable warn on error for now, while our sphinx env is still in flux
+                          -c "${SPHINX_BUILD_DIR}"
+                          -d "${SPHINX_CACHE_DIR}"
+                          "${CMAKE_CURRENT_SOURCE_DIR}"
+                          "${SPHINX_HTML_DIR}"
+                          COMMENT "Building HTML documentation with Sphinx"
+                          DEPENDS ${deps})
+    else()
+        add_custom_target(${sphinx_target_name}
+                          ${SPHINX_EXECUTABLE}
+                          -q -b html
+                          #-W disable warn on error for now, while our sphinx env is still in flux
+                          -d "${SPHINX_CACHE_DIR}"
+                          "${CMAKE_CURRENT_SOURCE_DIR}"
+                          "${SPHINX_HTML_DIR}"
+                          COMMENT "Building HTML documentation with Sphinx"
+                          DEPENDS ${deps})
+    endif()
     # hook our new target into the docs dependency chain
     add_dependencies(sphinx_docs ${sphinx_target_name})
 

src/docs/sphinx/building.rst

@@ -164,7 +164,7 @@ These files use standard CMake commands. CMake *set* commands need to specify th
 
 Bootstrapping Third Party Dependencies 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-We use **Spack** (http://software.llnl.gov/spack) automate builds of third party dependencies on OSX and Linux. Conduit builds on Windows as well, but there is no automated process to build dependencies necessary to support Conduit's optional features.
+We use **Spack** (http://software.llnl.gov/spack) to automate builds of third party dependencies on OSX and Linux. Conduit builds on Windows as well, but there is no automated process to build dependencies necessary to support Conduit's optional features.
 
 On OSX and Linux, you can use ``bootstrap-env.sh`` (located at the root of the conduit repo) to help setup your development environment. This script uses ``scripts/uberenv/uberenv.py``, which leverages **Spack** to build all of the external third party libraries and tools used by Conduit. Fortran support is optional and all dependencies should build without a fortran compiler. After building these libraries and tools, it writes an initial *host-config* file and adds the Spack built CMake binary to your PATH so can immediately call the ``config-build.sh`` helper script to configure a conduit build.
 

src/docs/sphinx/conf.py.in → src/docs/sphinx/conf.py

@@ -314,13 +314,14 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
-# try to add add breathe support
-try:
-    import breathe
-    breathe_projects = { "conduit ": "@CMAKE_CURRENT_BINARY_DIR@/../doxygen/xml/" }
-    breathe_default_project = "conduit"
-except:
-    pass
+# disable breath support for now
+# add breathe support
+#try:
+#    import breathe
+#    breathe_projects = { "conduit ": "@CMAKE_CURRENT_BINARY_DIR@/../doxygen/xml/" }
+#    breathe_default_project = "conduit"
+#except:
+#    pass
 
 # try to use the read the docs theme
 try:

src/docs/sphinx/tutorial_ownership.rst

@@ -54,7 +54,7 @@ The *Node* class provides two ways to hold data, the data is either **owned** or
 *set* vs *set_external* 
 --------------------------------
 
-The **Node::set** methods support creating **owned** data and coping data values in both the **owned** and **externally described** cases. The **Node::set_external** methods allow you to create **externally described** data:
+The **Node::set** methods support creating **owned** data and copying data values in both the **owned** and **externally described** cases. The **Node::set_external** methods allow you to create **externally described** data:
 
 - **set(...)**: Makes a copy of the data passed into the *Node*. This will trigger an allocation if the current data type of the *Node* is incompatible with what was passed. The *Node* assignment operators use their respective **set** variants, so they follow the same copy semantics. 
 

src/docs/sphinx/tutorial_update.rst

@@ -49,6 +49,7 @@ Node Update Methods
 The *Node* class provides three **update** methods which allow you to easily copy data or  the description of data from a source node. 
 
 - **Node::update(Node &source)**: 
+
  This method behaves similar to a python dictionary update. Entires from the source Node are copied into the calling Node, here are more concrete details:
 
  - **If the source describes an Object**: 
@@ -64,9 +65,11 @@ The *Node* class provides three **update** methods which allow you to easily cop
    - Update works exactly like a **set** (not true yet).
 
 - **Node::update_compatible(Node &source)**: 
+
  This method copies data from the children in the source Node that are compatible with children in the calling node. No changes are made where children are incompatible. 
 
 - **Node::update_external(Node &source)**: 
+
  This method creates children in the calling Node that externally describe the children in the source node. It differs from **Node::set_external(Node &source)** in that **set_external()** will clear the calling Node so it exactly match an external description of the source Node, whereas **update_external()** will only change the children in the calling Node that correspond to children in the source Node.