add to_string methods to core classes (#549)

* py relay mpi remove uness debug print statements

* add to_string methods to core classes

* schema: deprecate detailed arg for save and to_json methods

* eye crossing docs updates to use beg end sphinx style

* tweak yaml output to supress extra newlines

* py add node to_string()

* update change log

CHANGELOG.md

@@ -14,6 +14,8 @@ and this project aspires to adhere to [Semantic Versioning](https://semver.org/s
 - Added Node::fetch_existing and Schema::fetch_existing methods, which provide access to existing paths or error when given a bad path.
 - Added Node::add_child() and Node::remove_child() to support direct operatrions and cases where names have `/`s.
 - Added a set of conduit::utils::log::remove_* filtering functions, which process conduit log/info nodes and strip out the requested information (useful for focusing the often verbose output in log/info nodes).
+- Added to_string() and to_string_default() methods to Node, Schema, DataType, and DataArray. These methods alias either to_yaml() or to_json(). Long term yaml will be preferred over json, but Schema does not support yaml yet.
+- Added helper script (scripts/regen_docs_outputs.py) that regenerates all example outputs used Conduit's Sphinx docs.
 
 #### Relay
 - Added an open mode option to RelayIOHandle. See RelayIOHandle docs (https://llnl-conduit.readthedocs.io/en/latest/relay_io.html#relay-i-o-handle-interface) for more details.
@@ -36,6 +38,11 @@ and this project aspires to adhere to [Semantic Versioning](https://semver.org/s
 
 #### General 
 - Node::fetch_child and Schema::fetch_child are deprecated in favor of the more clearly named Node::fetch_existing and Schema::fetch_existing. fetch_child variants still exist, but will be removed in a future release.
+- Python str() methods for Node, Schema, and DataType now use their new to_string() methods.
+- DataArray<T>::to_json(std::ostring &) is deprecated in favor DataArray<T>::to_json_stream. to_json(std::ostring &) will be removed in a future release.
+- Schema::to_json and Schema::save variants with detailed (bool) arg are deprecated. The detailed arg was never used. These methods will be removed in a future release.
+- Node::print() now prints yaml instead of json.
+- Sphinx Docs code examples and outputs are now included using start-after and end-before style includes.
 
 #### Relay
 - Provide more context when a Conduit Node cannot be written to a HDF5 file because it is incompatible with the existing HDF5 tree. Error messages now provide the full path and details about the incompatibility.

scripts/regen_docs_outputs.py

@@ -0,0 +1,37 @@
+#! /usr/bin/env python
+# note: run in build dir, expects src to be ../src from build dir
+import subprocess
+import os
+
+from os.path import join as pjoin
+
+tests = ["t_conduit_docs_tutorial_basics",
+         "t_conduit_docs_tutorial_numeric",
+         "t_conduit_docs_tutorial_parse",
+         "t_conduit_docs_tutorial_ownership",
+         "t_conduit_docs_tutorial_errors",
+         # bp
+         "t_conduit_docs_blueprint_demos",
+         "t_conduit_docs_blueprint_examples",
+         "t_conduit_docs_relay_io_generic_examples",
+         "t_conduit_docs_relay_io_handle_examples",
+         "t_conduit_docs_relay_io_hdf5_examples",
+         # python
+         "t_conduit_docs_tutorial_python_basics",
+         "t_conduit_docs_tutorial_python_numeric",
+         "t_conduit_docs_tutorial_python_ownership",
+         "t_conduit_docs_tutorial_python_parse",
+         "t_conduit_docs_tutorial_python_relay_io_handle_examples",
+         "t_conduit_docs_tutorial_python_relay_mpi_examples"]
+
+
+dest_dir = "../src/docs/sphinx/"
+out_suffix = "_out.txt"
+
+for test in tests:
+    if "python" in test:
+        cmd = "ctest -VV -R {} > {}_out.txt".format(test,pjoin(dest_dir,test))
+    else:
+        cmd = "tests/docs/{} > {}_out.txt".format(test,pjoin(dest_dir,test))
+    print(cmd)
+    subprocess.call(cmd,shell=True)

src/docs/sphinx/blueprint.rst

@@ -86,26 +86,30 @@ Blueprint provides a generic top level ``verify()`` method, which exposes the ve
 ``verify()`` returns true if the passed Node *node* conforms to the named protocol. It also provides details about the verification, including specific errors in the passed *info* Node.
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_examples.cpp
-   :lines: 65-79
+   :start-after: BEGIN_EXAMPLE("blueprint_example_1")
+   :end-before:  END_EXAMPLE("blueprint_example_1")
    :language: cpp
    :dedent: 4
 
+
 .. literalinclude:: t_conduit_docs_blueprint_examples_out.txt
-   :lines: 10-19
+   :start-after: BEGIN_EXAMPLE("blueprint_example_1")
+   :end-before:  END_EXAMPLE("blueprint_example_1")
 
 
 
 Methods for specific protocols are grouped in namespaces:
 
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_examples.cpp
-   :lines: 90-116
+   :start-after: BEGIN_EXAMPLE("blueprint_example_2")
+   :end-before:  END_EXAMPLE("blueprint_example_2")
    :language: cpp
    :dedent: 4
 
 .. literalinclude:: t_conduit_docs_blueprint_examples_out.txt
-   :lines: 26-83
-
+   :start-after: BEGIN_EXAMPLE("blueprint_example_2")
+   :end-before:  END_EXAMPLE("blueprint_example_2")
 
 
 

src/docs/sphinx/blueprint_mesh.rst

@@ -629,16 +629,17 @@ Uniform
 * **Usage Example**
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 138-143
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_uniform")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_uniform")
    :language: cpp
    :dedent: 4
 
 * **Result**
 
-.. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 146-187
-   :language: cpp
-   :dedent: 4
+.. literalinclude:: t_conduit_docs_blueprint_demos_out.txt
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_uniform")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_uniform")
+   :language: yaml
 
 * **Visual**
 
@@ -654,16 +655,17 @@ Rectilinear
 * **Usage Example**
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 197-201
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_rectilinear")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_rectilinear")
    :language: cpp
    :dedent: 4
 
 * **Result**
 
-.. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 204-235
-   :language: cpp
-   :dedent: 4
+.. literalinclude:: t_conduit_docs_blueprint_demos_out.txt
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_rectilinear")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_rectilinear")
+   :language: yaml
 
 * **Visual**
 
@@ -679,16 +681,17 @@ Structured
 * **Usage Example**
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 244-249
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_structured")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_structured")
    :language: cpp
    :dedent: 4
 
 * **Result**
 
-.. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 252-291
-   :language: cpp
-   :dedent: 4
+.. literalinclude:: t_conduit_docs_blueprint_demos_out.txt
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_structured")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_structured")
+   :language: yaml
 
 * **Visual**
 
@@ -704,16 +707,17 @@ Tris
 * **Usage Example**
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 300-305
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_tris")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_tris")
    :language: cpp
    :dedent: 4
 
 * **Result**
 
-.. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 308-344
-   :language: cpp
-   :dedent: 4
+.. literalinclude:: t_conduit_docs_blueprint_demos_out.txt
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_tris")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_tris")
+   :language: yaml
 
 * **Visual**
 
@@ -729,16 +733,17 @@ Quads
 * **Usage Example**
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 353-358
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_quads")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_quads")
    :language: cpp
    :dedent: 4
 
 * **Result**
 
-.. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 361-397
-   :language: cpp
-   :dedent: 4
+.. literalinclude:: t_conduit_docs_blueprint_demos_out.txt
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_quads")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_quads")
+   :language: yaml
 
 * **Visual**
 
@@ -754,16 +759,17 @@ Polygons
 * **Usage Example**
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 514-519
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_polygons")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_polygons")
    :language: cpp
    :dedent: 4
 
 * **Result**
 
-.. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 522-558
-   :language: cpp
-   :dedent: 4
+.. literalinclude:: t_conduit_docs_blueprint_demos_out.txt
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_polygons")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_polygons")
+   :language: yaml
 
 * **Visual**
 
@@ -779,16 +785,17 @@ Tets
 * **Usage Example**
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 406-411
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_tets")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_tets")
    :language: cpp
    :dedent: 4
 
 * **Result**
 
-.. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 414-451
-   :language: cpp
-   :dedent: 4
+.. literalinclude:: t_conduit_docs_blueprint_demos_out.txt
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_tets")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_tets")
+   :language: yaml
 
 * **Visual**
 
@@ -804,16 +811,17 @@ Hexs
 * **Usage Example**
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 460-465
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_hexs")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_hexs")
    :language: cpp
    :dedent: 4
 
 * **Result**
 
-.. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 468-505
-   :language: cpp
-   :dedent: 4
+.. literalinclude:: t_conduit_docs_blueprint_demos_out.txt
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_hexs")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_hexs")
+   :language: yaml
 
 * **Visual**
 
@@ -829,16 +837,17 @@ Polyhedra
 * **Usage Example**
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 567-572
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_polyhedra")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_polyhedra")
    :language: cpp
    :dedent: 4
 
 * **Result**
 
-.. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 575-612
-   :language: cpp
-   :dedent: 4
+.. literalinclude:: t_conduit_docs_blueprint_demos_out.txt
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_polyhedra")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_polyhedra")
+   :language: yaml
 
 * **Visual**
 
@@ -1062,7 +1071,8 @@ This snippet provides a complete C++ example that demonstrates:
   * Saving the result to a JSON file that VisIt can open
 
 .. literalinclude:: ../../tests/docs/t_conduit_docs_blueprint_demos.cpp
-   :lines: 621-680
+   :start-after: BEGIN_EXAMPLE("blueprint_demo_basic_uniform_detailed")
+   :end-before:  END_EXAMPLE("blueprint_demo_basic_uniform_detailed")
    :language: cpp
    :dedent: 4