From 06cea3a003c73c519c35f32bbd456066e0e842d1 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Thu, 31 Oct 2024 22:18:04 +0000 Subject: [PATCH 1/8] break sidebar into sections --- docs/source/index.rst | 50 ++++++++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 17 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index a81ac75..2bf6366 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -83,17 +83,21 @@ 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 model_grids - csdms + BMI-based tools glossary references @@ -101,31 +105,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: From a83f59cbcb0ad80b44743fbda49d3347c9dc3898 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 4 Nov 2024 14:00:14 +0000 Subject: [PATCH 2/8] add a table of contents to the spec page --- docs/source/bmi.spec.rst | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index 5c66083..4deb876 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -6,12 +6,16 @@ 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 + + Metadata + Control + Info + Variables + Time + Getters and setters + Grid Table 3 lists the individual BMI functions along with a brief description. @@ -69,14 +73,6 @@ grouped by functional category. :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 From 0271088828230e64e3108f277a59524b08710901 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 4 Nov 2024 14:01:10 +0000 Subject: [PATCH 3/8] add the spec page to the table of contents --- docs/source/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 2bf6366..d931f2e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -81,8 +81,6 @@ 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: @@ -96,6 +94,7 @@ A complete description of the functions that make up the BMI is given next. :hidden: :maxdepth: 2 + BMI Spec model_grids BMI-based tools glossary From 16b1921b80859c7a9e31ead02e91caa95e57577d Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 4 Nov 2024 14:08:52 +0000 Subject: [PATCH 4/8] add a links file; move external links to links file --- docs/source/bmi.spec.rst | 9 --------- docs/source/links.rst | 9 +++++++++ 2 files changed, 9 insertions(+), 9 deletions(-) create mode 100644 docs/source/links.rst diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index 4deb876..7c195d4 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -72,12 +72,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. ============================== ========================================= - -.. - 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/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 From f4d73d9dd24c18866f84badff9ddb0fc830d0316 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 4 Nov 2024 14:11:07 +0000 Subject: [PATCH 5/8] include links file for external links --- docs/source/bmi.getter_setter.rst | 2 ++ docs/source/bmi.time_funcs.rst | 2 ++ docs/source/bmi.var_funcs.rst | 5 +---- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/bmi.getter_setter.rst b/docs/source/bmi.getter_setter.rst index e3eb1c4..3c52b96 100644 --- a/docs/source/bmi.getter_setter.rst +++ b/docs/source/bmi.getter_setter.rst @@ -164,3 +164,5 @@ Additionally, * 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.time_funcs.rst b/docs/source/bmi.time_funcs.rst index 2328057..85ff49e 100644 --- a/docs/source/bmi.time_funcs.rst +++ b/docs/source/bmi.time_funcs.rst @@ -131,3 +131,5 @@ The time step is always expressed as a floating point value. (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..f8fd2ef 100644 --- a/docs/source/bmi.var_funcs.rst +++ b/docs/source/bmi.var_funcs.rst @@ -183,7 +183,4 @@ element the variable is defined. Valid return values are: [:ref:`var_funcs` | :ref:`basic_model_interface`] - -.. Links - -.. _dtype: https://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html +.. include:: links.rst From f750143be686c15a9dc8e8302ff443262559d6d2 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Mon, 4 Nov 2024 14:12:27 +0000 Subject: [PATCH 6/8] don't exclude any files from the docs --- docs/source/conf.py | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) 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. From 516d1caa00949f872ff2fcbe78ba8263755aed34 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Tue, 5 Nov 2024 11:04:34 +0000 Subject: [PATCH 7/8] remove links to top of section and main page --- docs/source/bmi.control_funcs.rst | 8 -------- docs/source/bmi.getter_setter.rst | 10 ---------- docs/source/bmi.grid_funcs.rst | 32 ------------------------------- docs/source/bmi.info_funcs.rst | 10 ---------- docs/source/bmi.time_funcs.rst | 10 ---------- docs/source/bmi.var_funcs.rst | 12 ------------ 6 files changed, 82 deletions(-) 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 3c52b96..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,6 +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.time_funcs.rst b/docs/source/bmi.time_funcs.rst index 85ff49e..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,6 +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 f8fd2ef..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,6 +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`] - .. include:: links.rst From 92cdf7ba28bac3fa8d73b032b80a67f595043fb9 Mon Sep 17 00:00:00 2001 From: mcflugen Date: Wed, 20 Nov 2024 21:15:20 -0700 Subject: [PATCH 8/8] remove reference to metadata functions --- docs/source/bmi.spec.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/bmi.spec.rst b/docs/source/bmi.spec.rst index 7c195d4..cd797fd 100644 --- a/docs/source/bmi.spec.rst +++ b/docs/source/bmi.spec.rst @@ -9,7 +9,6 @@ can be grouped into categories: .. toctree:: :maxdepth: 1 - Metadata Control Info Variables