Merge pull request #166 from csdms/mcflugen/stable-split-bmi-spec-int…

…o-separate-pages Split the bmi spec into multiple pages on stable branch
csdms · Nov 21, 2024 · bafe7f2 · bafe7f2
2 parents 0396e8e + 92cdf7b
commit bafe7f2
Show file tree

Hide file tree

Showing 10 changed files with 56 additions and 136 deletions.
diff --git a/docs/source/bmi.control_funcs.rst b/docs/source/bmi.control_funcs.rst
@@ -42,8 +42,6 @@ formatted.
 * In C and Fortran, an integer status code indicating success (zero) or failure (nonzero)
   is returned. In C++, Java, and Python, an exception is raised on failure.
 
-[:ref:`control_funcs` | :ref:`basic_model_interface`]
-
 
 .. _update:
 
@@ -71,8 +69,6 @@ function can just return without doing anything.
 * In C and Fortran, an integer status code indicating success (zero) or failure (nonzero)
   is returned. In C++, Java, and Python, an exception is raised on failure.
 
-[:ref:`control_funcs` | :ref:`basic_model_interface`]
-
 
 .. _update_until:
 
@@ -99,8 +95,6 @@ to reflect that the model was updated to the requested time.
 * In C and Fortran, an integer status code indicating success (zero) or failure (nonzero)
   is returned. In C++, Java, and Python, an exception is raised on failure.
 
-[:ref:`control_funcs` | :ref:`basic_model_interface`]
-
 
 .. _finalize:
 
@@ -121,5 +115,3 @@ deallocating memory, closing files and printing reports.
 
 * In C and Fortran, an integer status code indicating success (zero) or failure (nonzero)
   is returned. In C++, Java, and Python, an exception is raised on failure.
-
-[:ref:`control_funcs` | :ref:`basic_model_interface`]
diff --git a/docs/source/bmi.getter_setter.rst b/docs/source/bmi.getter_setter.rst
@@ -49,8 +49,6 @@ even if the model uses dimensional variables.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
-
 .. _get_value_ptr:
 
 *get_value_ptr*
@@ -77,8 +75,6 @@ even if the model's state has changed.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_value_at_indices:
 
@@ -103,8 +99,6 @@ Additionally,
 * Both *dest* and *inds* are flattened arrays.
 * The *inds* argument is always of type integer.
 
-[:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
-
 
 .. _set_value:
 
@@ -138,8 +132,6 @@ even if the model uses dimensional variables.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
-
 
 .. _set_value_at_indices:
 
@@ -163,4 +155,4 @@ Additionally,
 * Both *src* and *inds* are flattened arrays.
 * The *inds* argument is always of type integer.
 
-[:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
+.. include:: links.rst
diff --git a/docs/source/bmi.grid_funcs.rst b/docs/source/bmi.grid_funcs.rst
@@ -54,8 +54,6 @@ is given in the :ref:`model_grids` section.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_rank:
 
@@ -84,8 +82,6 @@ of :ref:`get_grid_x`, :ref:`get_grid_y`, etc. are implemented.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_size:
 
@@ -114,8 +110,6 @@ for :ref:`unstructured <unstructured_grids>` and
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_shape:
 
@@ -154,8 +148,6 @@ the cells.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_spacing:
 
@@ -185,8 +177,6 @@ the spacing between rows is followed by spacing between columns, ``[dy, dx]``.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_origin:
 
@@ -217,8 +207,6 @@ the origin is given in the column dimension, followed by the row dimension,
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_x:
 
@@ -247,8 +235,6 @@ See :ref:`model_grids` for more information.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_y:
 
@@ -277,8 +263,6 @@ See :ref:`model_grids` for more information.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_z:
 
@@ -307,8 +291,6 @@ See :ref:`model_grids` for more information.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_node_count:
 
@@ -331,8 +313,6 @@ Get the number of :term:`nodes <node>` in the grid.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_edge_count:
 
@@ -355,8 +335,6 @@ Get the number of :term:`edges <edge>` in the grid.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_face_count:
 
@@ -379,8 +357,6 @@ Get the number of :term:`faces <face>` in the grid.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_edge_nodes:
 
@@ -407,8 +383,6 @@ node at edge head. The total length of the array is
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_face_edges:
 
@@ -434,8 +408,6 @@ The length of the array returned is the sum of the values of
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_face_nodes:
 
@@ -466,8 +438,6 @@ the length of the array is the sum of the values of
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_grid_nodes_per_face:
 
@@ -492,5 +462,3 @@ The number of edges per face is equal to the number of nodes per face.
 * In C++ and Java, this is a void function.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
-
-[:ref:`grid_funcs` | :ref:`basic_model_interface`]
diff --git a/docs/source/bmi.info_funcs.rst b/docs/source/bmi.info_funcs.rst
@@ -29,8 +29,6 @@ but it should be unique to prevent conflicts with other components.
 * In C++, Java, and Python, this argument is omitted, and a string -- a basic type
   in these languages -- is returned from the function.
 
-[:ref:`info_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_input_item_count:
 
@@ -53,8 +51,6 @@ Also the number of variables that can be set with :ref:`set_value`.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`info_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_output_item_count:
 
@@ -77,8 +73,6 @@ Also the number of variables that can be retrieved with :ref:`get_value`.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`info_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_input_var_names:
 
@@ -113,8 +107,6 @@ Standard Names do not have to be used within the model.
   function in a tuple, a standard container in the language.
 * A model might have no input variables.
 
-[:ref:`info_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_output_var_names:
 
@@ -148,5 +140,3 @@ Standard Names do not have to be used within the model.
 * In Python, the argument is omitted and the names are returned from the
   function in a tuple, a standard container in the language.
 * A model may have no output variables.
-
-[:ref:`info_funcs` | :ref:`basic_model_interface`]
diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst
@@ -6,12 +6,15 @@ The Basic Model Interface
 The functions that comprise the Basic Model Interface
 can be grouped into categories:
 
-* :ref:`control_funcs`
-* :ref:`info_funcs`
-* :ref:`var_funcs`
-* :ref:`time_funcs`
-* :ref:`getter_setter_funcs`
-* :ref:`grid_funcs`
+.. toctree::
+   :maxdepth: 1
+
+   Control <bmi.control_funcs>
+   Info <bmi.info_funcs>
+   Variables <bmi.var_funcs>
+   Time <bmi.time_funcs>
+   Getters and setters <bmi.getter_setter>
+   Grid <bmi.grid_funcs>
 
 Table 3 lists the individual BMI functions
 along with a brief description.
@@ -68,20 +71,3 @@ grouped by functional category.
    :ref:`get_grid_face_nodes`      Get the face-node connectivity.
    :ref:`get_grid_nodes_per_face`  Get the number of nodes for each face.
    ==============================  =========================================
-
-.. include:: bmi.control_funcs.rst
-.. include:: bmi.info_funcs.rst
-.. include:: bmi.var_funcs.rst
-.. include:: bmi.time_funcs.rst
-.. include:: bmi.getter_setter.rst
-.. include:: bmi.grid_funcs.rst
-
-
-..
-   Links
-
-.. _UDUNITS: https://www.unidata.ucar.edu/software/udunits/
-.. _The Units Database: https://docs.unidata.ucar.edu/udunits/current/#Database
-.. _time unit conventions: https://docs.unidata.ucar.edu/udunits/current/udunits2-accepted.xml
-.. _primitive types: https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html
-.. _wrapper classes: https://docs.oracle.com/javase/tutorial/java/data/numberclasses.html
diff --git a/docs/source/bmi.time_funcs.rst b/docs/source/bmi.time_funcs.rst
@@ -25,8 +25,6 @@ The current model time.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`time_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_start_time:
 
@@ -48,8 +46,6 @@ The start time of the  model.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`time_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_end_time:
 
@@ -73,8 +69,6 @@ The end time of the  model.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`time_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_time_units:
 
@@ -104,8 +98,6 @@ It's recommended to use `time unit conventions`_ from Unidata's
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`time_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_time_step:
 
@@ -130,4 +122,4 @@ The time step is always expressed as a floating point value.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`time_funcs` | :ref:`basic_model_interface`]
+.. include:: links.rst
diff --git a/docs/source/bmi.var_funcs.rst b/docs/source/bmi.var_funcs.rst
@@ -39,8 +39,6 @@ A model can have one or more grids.
 * In C and Fortran, an integer status code indicating success (zero) or
   failure (nonzero) is returned.
 
-[:ref:`var_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_var_type:
 
@@ -68,8 +66,6 @@ while in Fortran, use `integer`, `real`, and `double precision`.
 * In Java, only `primitive types`_ (e.g., ``int``, ``double``), not
   `wrapper classes`_ (e.g., ``Integer``, ``Double``), are supported.
 
-[:ref:`var_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_var_units:
 
@@ -103,8 +99,6 @@ full description of valid unit names and a list of supported units.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`var_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_var_itemsize:
 
@@ -128,8 +122,6 @@ For example, if data for a variable are stored as 64-bit integers,
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`var_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_var_nbytes:
 
@@ -151,8 +143,6 @@ a variable; i.e., the number of items multiplied by the size of each item.
 * In C and Fortran, an integer status code indicating success (zero) or failure
   (nonzero) is returned.
 
-[:ref:`var_funcs` | :ref:`basic_model_interface`]
-
 
 .. _get_var_location:
 
@@ -181,9 +171,4 @@ element the variable is defined. Valid return values are:
 * If the given variable is a scalar (i.e., defined on a :ref:`scalar
   grid <unstructured_grids>`), the location from this function is ignored.
 
-[:ref:`var_funcs` | :ref:`basic_model_interface`]
-
-
-.. Links
-
-.. _dtype: https://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html
+.. include:: links.rst