Updated documentation accordingly for qfyaml 0.3.1

docs/source/known_bugs.rst
- Add info about error returning long YAML sequences in v0.3.0
- Add info about array sizes restriction for QFYAML_Add_Get in v0.3.0

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

docs/source/known-bugs.rst

@@ -39,3 +39,27 @@ Use underscores instead of spaces in YAML sequence items:
    - Star_fruit
 
 And then you can remove the underscores in post-processing.
+
+Error returning long YAML sequences
+===================================
+
+It was discovered that only a subset long YAML sequences were being
+returned.  Upon further investigation, a string variable in routine
+:file:`Get_Fields_string` was found to be too short to hold all of the
+stored data within a YAML variable.
+
+We have fixed this behavior in :program:`qfyaml 0.3.1`.
+
+Arrays passed to QFYAML_Add_Get had to be the same size as the data in
+the YAML file
+===================================
+
+When passing an array to routine :file:`QFYAML_Add_Get`, an error
+would be returned if the array was not the same length as the array or
+sequence in the YAML file.
+
+In :program:`qfyaml 0.3.1`, arrays that are larger than the size of
+the data may be passed to :file:`QFYAML_Add_Get`.  This will let you
+declare an array size that is sufficiently large in the calling
+routine.  This can be especially useful if you do not know the size of
+the data to be read in from the YAML file.

docs/source/running-tests.rst

@@ -37,8 +37,8 @@ output.  If the test is successful you will see this output:
 
 .. code-block:: console
 
-   ### Reading input.yml
-   
+   ### Reading qfyaml.yml
+
    ### YAML VARIABLES
    author%age                       :      29
    author%fav_reals                 :    1.00   2.00
@@ -51,28 +51,28 @@ output.  If the test is successful you will see this output:
    weather%temperature%daily        :     23.043436
    weather%temperature%weekly%units : K
    weather%pressure                 :   1013.250000
-   
+
    ### YAML SEQUENCES
    fruits
               1 Apples
               2 Bananas
               3 Oranges
-   
+
    more_fruits%p_fruits
               1 Pears
               2 Plums
               3 Peaches
               4 Pomegranites
-   
+
    even_more_fruits%exotic_fruits%hard_to_find
               1 Kumquats
               2 Kiwi
               3 Passion_fruit
               4 Star_fruit
               5 Durians
-   
+
    #### finishing
-		
+
 .. _geos-chem_tests:
 
 ********************************
@@ -81,16 +81,16 @@ GEOS-Chem-specific test programs
 
 The following test programs can be used to debug source code for
 reading YAML-format configuration files into the `GEOS-Chem model
-<https://geos-chem.org>`_. 
+<https://geos-chem.org>`_.
 
-.. _test_geoschem_config.x:
+.. _test_input_options.x:
 
-test_geoschem_config.x
+test_input_options.x
 ======================
 
 This test program attempts to read the `GEOS-Chem master configuration
 file
-<https://github.com/yantosca/qfyaml/blob/main/test/geoschem_config.yml>`_
+<https://github.com/yantosca/qfyaml/blob/main/test/input_options.yml>`_
 and echo back output.  The master configuration file will replace
 :file:`input.geos` in GEOS-Chem 14.0.0 and later.
 
@@ -99,33 +99,48 @@ To run this test, type at the command line:
 .. code-block:: console
 
    $ cd qfyaml/bin      # Skip if you are already in qfyaml/bin
-   $ ./test_geoschem_config.x
+   $ ./test_input_options.x
 
 And you should see output such as:
 
 .. code-block :: console
 
-   ### Reading geoschem_config.yml
-                               simulation%start |   20190701         0
-                                 simulation%end |   20190801         0
-                           simulation%met_field | MERRA2
-                                simulation%name | UNKNOWN
-               simulation%species_database_file | species_database.yml
-                      simulation%debug_printout |          F
-                simulation%use_gcclassic_timers |          F
-   ---
-                                grid%resolution | 0.5x0.625
-                           grid%longitude_range |    -140.00    -40.00
-                         grid%center_lon_at_180 |          T
-                            grid%latitude_range |     -10.00     70.00
-                     grid%half_size_polar_boxes |          T
-                          grid%number_of_levels |         72
-                    grid%nested_grid_simulation |          T
-                          grid%buffer_zone_NSEW |          3         3         3         3
-   ---
-             timesteps%transport_and_convection |        300
-              timesteps%chemistry_and_emissions |        600
-   ... etc ...
+   ### Reading input_options.yml
+    simulation%start
+    ==>     20190701           0
+    simulation%end
+    ==>     20190801           0
+    simulation%data_dir
+    ==> /n/holyscratch01/external_repos/GEOS-CHEM/gcgrid/data/ExtData
+    simulation%met_field
+    ==> MERRA2
+    simulation%name
+    ==> fullchem
+    simulation%species_database_file
+    ==> species_database.yml
+    simulation%debug_printout
+    ==>  F
+    simulation%use_gcclassic_timers
+    ==>  F
+
+    grid%resolution
+    ==> 0.5x0.625
+    grid%longitude_range
+    ==>   -140.000000      -40.0000000
+    grid%center_lon_at_180
+    ==>  T
+    grid%latitude_range
+    ==>   -10.0000000       70.0000000
+    grid%half_size_polar_boxes
+    ==>  T
+    grid%number_of_levels
+    ==>           72
+    grid%nested_grid_simulation
+    ==>  T
+    grid%buffer_zone_NSEW
+    ==>            3           3           3           3
+
+    . . . etc . . .
 
 .. _test_species_database.x:
 
@@ -186,9 +201,5 @@ You should see output similar to this:
                ACTA%WD_RainoutEff |    -999.00   -999.00   -999.00
            ACTA%WD_RainoutEff_Luo |    -999.00   -999.00   -999.00
                 ACTA%WD_RetFactor |       0.02
-   
-   ... etc for other species ...
-
-
-
 
+   . . . etc . . .