diff --git a/docs/source/bmi.control_funcs.rst b/docs/source/bmi.control_funcs.rst index f75cb1f..e08751c 100644 --- 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 index e3eb1c4..f1dc834 100644 --- 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 index df9fc08..a494dbc 100644 --- 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 ` 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 ` 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 ` 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 ` 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 index 74f4ba9..236db5f 100644 --- 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 index 5c66083..cd797fd 100644 --- 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 + Info + Variables + Time + Getters and setters + Grid 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 index 2328057..b8b0a0f 100644 --- 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 index 2cdb601..bfb6b3b 100644 --- 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 `), 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 diff --git a/docs/source/conf.py b/docs/source/conf.py index f51e9e7..d332343 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -75,16 +75,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [ - "bmi.spec.rst", - "bmi.control_funcs.rst", - "bmi.info_funcs.rst", - "bmi.var_funcs.rst", - "bmi.time_funcs.rst", - "bmi.getter_setter.rst", - "bmi.grid_funcs.rst", - "bmi.metadata_funcs.rst", -] +exclude_patterns = [] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/source/index.rst b/docs/source/index.rst index a81ac75..d931f2e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -81,19 +81,22 @@ two documents may be particularly helpful when writing a BMI: A complete description of the functions that make up the BMI is given next. -.. include:: bmi.spec.rst - +.. toctree:: + :caption: Getting Started + :hidden: + :maxdepth: 2 -Additional Topics -================= + How to + bmi.best_practices .. toctree:: + :caption: Reference + :hidden: :maxdepth: 2 - bmi.getting_started - bmi.best_practices + BMI Spec model_grids - csdms + BMI-based tools glossary references @@ -101,31 +104,43 @@ BMI is an element of the `CSDMS Workbench`_, an integrated system of software tools, technologies, and standards for building and coupling models. +.. + Help + ---- -Help ----- - -Adding a BMI to a model can be a daunting task. -If you'd like assistance, -CSDMS can help. -Depending on your need, we can provide advice or consulting services. -Feel free to contact us through the `CSDMS Help Desk`_. + Adding a BMI to a model can be a daunting task. + If you'd like assistance, + CSDMS can help. + Depending on your need, we can provide advice or consulting services. + Feel free to contact us through the `CSDMS Help Desk`_. +.. toctree:: + :caption: Contrubuting + :hidden: + :maxdepth: 1 -Project Information -------------------- + contributing + Code of Conduct .. toctree:: + :caption: About + :hidden: :maxdepth: 1 citation - contributing - conduct credits Governance council partners +.. toctree:: + :caption: Project Links + :hidden: + :maxdepth: 1 + + Help + GitHub + Docs .. Links: diff --git a/docs/source/links.rst b/docs/source/links.rst new file mode 100644 index 0000000..5668eb9 --- /dev/null +++ b/docs/source/links.rst @@ -0,0 +1,9 @@ +.. + Links + +.. _The Units Database: https://docs.unidata.ucar.edu/udunits/current/#Database +.. _UDUNITS: https://www.unidata.ucar.edu/software/udunits/ +.. _dtype: https://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html +.. _primitive types: https://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html +.. _time unit conventions: https://docs.unidata.ucar.edu/udunits/current/udunits2-accepted.xml +.. _wrapper classes: https://docs.oracle.com/javase/tutorial/java/data/numberclasses.html