Merge topic 'docs-data-source-no-path'

a82653a5 Update documentation to match changes to BP file finding

Acked-by: Kitware Robot <kwrobot@kitware.com>
Reviewed-by: Caitlin Ross <caitlin.ross@kitware.com>
Merge-request: !173

docs/user_guide/source/components/datasetreader.rst

@@ -111,7 +111,13 @@ Reading Metadata
 ================
 
 The next step is to read the metadata, which will give you info such as number of steps, blocks, and available fields.
-In order to read metadata/data, you'll need to first set up the paths for the data source(s), then the metadata can be read as follows:
+
+.. code-block:: c++
+
+    auto metadata = reader.ReadMetaData();
+
+If any of the ``data_sources`` are set as ``input`` filename mode or the specified file is not relative to the JSON file, then you'll need to first set up the paths for the data source(s)
+In this case, the metadata can be read as follows:
 
 .. code-block:: c++
 
@@ -147,7 +153,8 @@ Reading Data
 ============
 
 Now we can read the actual data, in either random access mode or go step by step.
-In either case, we need the ``paths`` for the data source(s) we set up earlier before reading the metadata, as well as creating a new ``fides::metadata::MetaData`` object that we can use to give Fides some info on the selections we'd like to make.
+In either case, we need to create a new ``fides::metadata::MetaData`` object that we can use to give Fides some info on the selections we'd like to make.
+If a paths object was passed to the :func:`fides::io::DataSetReader::ReadMetaData` method, that also needs to be passed to the :func:`fides::io::DataSetReader::ReadDataSet` method.
 
 **Random access of data steps**
 
@@ -164,8 +171,13 @@ Now we can read the dataset:
 
 .. code-block:: c++
 
-    vtkm::cont::PartitionedDataSet output = reader.ReadDataSet(paths, selections);
+    vtkm::cont::PartitionedDataSet output = reader.ReadDataSet(selections);
+
+If you provided paths to :func:`fides::io::DataSetReader::ReadMetaData`, don't forget to also provide them here.
 
+.. code-block:: c++
+
+    vtkm::cont::PartitionedDataSet output = reader.ReadDataSet(paths, selections);
 
 Now you've got your data in VTK-m format, so you can use the VTK-m API to access the partitions, use filters, etc.
 
@@ -178,6 +190,23 @@ If any data source is not ready, Fides will internally loop on that data source
 In the case of multiple data sources, if some source hits ``EndOfStream`` before the others (e.g., mesh is stored in a different data source from the variable data and has only one step, while the variables have multiple steps), Fides caches the data from that data source and doesn't attempt to read steps that do not exist.
 When ``PrepareNextStep()`` returns ``EndOfStream`` that means all data sources have finished streaming.
 
+.. code-block:: c++
+
+    while (true)
+    {
+      fides::StepStatus status = reader.PrepareNextStep();
+      if (status == fides::StepStatus::EndOfStream)
+      {
+        // all
+        break;
+      }
+      // PrepareNextStep only returns EndOfStream or OK
+      vtkm::cont::PartitionedDataSet output = reader.ReadDataSet(selections);
+      // perform what ever vis/analysis tasks you want on this step
+    }
+
+Once again, if you are using a paths object to find BP files/streams, they will also need to be provided to :func:`fides::io::DataSetReader::PrepareNextStep` and :func:`fides::io::DataSetReader::ReadDataSet`.
+
 .. code-block:: c++
 
     while (true)

docs/user_guide/source/conf.py

@@ -72,6 +72,10 @@ templates_path = ['_templates']
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Coding examples are primarily in C++.
+primary_domain = 'cpp'
+highlight_language = 'cpp'
+
 
 # -- Options for HTML output -------------------------------------------------
 

docs/user_guide/source/schema/schema.rst

@@ -26,22 +26,26 @@ If you write all of your data using one engine (e.g., single BP file or stream),
 Some simulations write the mesh to a different file from the field data, so in this case, you would set up two data sources.
 
 
-The following example shows a single data source being defined. The ``name`` is any name you want to give it and is the name
+The following example shows a single data source being defined.
+The ``name`` is any name you want to give it and is the name
 Fides uses to track the data source.
-In most cases ``filename_mode`` will be ``input``. In this case, the specific filename is not given, and you will need to give the name to Fides in your code.
+In most cases ``filename_mode`` will be ``relative``.
+In this case, a specific ``filename`` is given to the actual name of teh BP file/stream.
+The file path is assumed to be relative to the location of the JSON file unless an alternate location is provided in the paths provided to the Fides reader methods.
+In the following example, Fides will look for a file named ``simulation_data.bp`` in the same directory as the JSON file.
 
 .. code-block:: json
 
     "data_sources": [
       {
       "name": "source",
-      "filename_mode": "input"
+      "filename_mode": "relative",
+      "filename": "simulation_data.bp"
       }
     ]
 
 The following example shows two data sources being defined, one for the mesh and one for the fields.
-The ``filename_mode`` is set to ``relative``, which means that ``filename`` is now required.
-Filename is the actual name of the BP file/stream. The path is not necessary, as that will be passed at runtime to Fides.
+In this case, each data source will load a different file.
 
 .. code-block:: json
 
@@ -49,12 +53,25 @@ Filename is the actual name of the BP file/stream. The path is not necessary, as
       {
         "name": "mesh",
         "filename_mode": "relative",
-        "filename": "mesh.bp"
+        "filename": "data/mesh.bp"
       },
       {
         "name": "fields",
         "filename_mode": "relative",
-        "filename": "fields.bp"
+        "filename": "data/fields.bp"
+      }
+    ]
+
+The following example shows a single data source being defined without naming the file by setting the ``filename_mode`` to ``input``.
+In this case, the specific filename is not given, and you will need to give the name to Fides in your code.
+This is done by providing a paths map that references the given ``name`` to the full path of the BP file/stream.
+
+.. code-block:: json
+
+    "data_sources": [
+      {
+      "name": "source",
+      "filename_mode": "input"
       }
     ]