docs: update docs for BMI v2 (#56)

* Remove .gitignore

It's not helping anything in this minimal repository.

* Remove examples from repository

The examples will instead be linked from the README and the docs.
This may less confusing than submodules. This fixes #46.

cc: @kbarnhart

* Remove language bindings from repository

The bindings will instead be linked from the README and the docs.
This may be less confusing than submodules.

* Remove trailing .gitmodules file

* Update text; add table and links

* Strike table title

* Revise and edit text

* Add Julian Hofer as a contributor

* Update version, date, and copyright holder

I booted @mcflugen. We can always revert this.

* Update opening paragraph

* Include descriptions of BMI functions in one document

Previously, they had been linked. This will make it easier to Ctrl-F
and search for information.

* Start a glossary of terms

I'll add to it as I move through and revise the docs.

* Reformat time functions section

Still need to add function descriptions and fix duplicate header
warnings.

* A few areas where I don't understand and some typos/reformatting

* Update the model control functions section

* Include Mike Galloy as contributor

* Break update and update_until into separate sections

My plan is to list each BMI function in its own section.

* Revise and format model information functions section

* Exclude source files that are included

This removes the duplicate label warning generated when source files
with labels are included in other source files.

* Update variable info functions section

This includes moving UDUNITS links from this section and the time
functions section up to the parent document, `bmi.spec.rst`.

* Update time functions section

* Fix awkward sentences, formatting

* Create summary table of BMI functions

* Start revising descriptions of get and set functions

* Stub out section on best proactices for implementing a BMI

This is really rough right now. Also, I'm not sure where to place
it in the docs.

* List the functional categories of BMI functions

This requires adding a reference link to the heading of each category
page.

* It's 2020

* Inlcude spec and examples links at beginning; move comments to end

* Add SIDL comment to each function prototype

I don't people to confuse the function prototype with another language.

* Complete getter/setter section

* Remove the BMI Bindings section

Instead, link to the most current bindings in their respective
GitHub repos. This is one way of preventing the docs from falling
out of sync with the language specifications.

* Experiment with section navigation links

Since we don't have a floating TOC, it's difficult to move quickly
within the single-page document. To address this, I've added links
after each BMI function back to the functional category header and to
the top header. If this looks good, I'll apply it to the other
sections.

* Add section header label

* Follow file naming convention for BMI docs

I also moved this "implementation" section to Additional Topics,
and retitled it "BMI best practices".

* Checkpoint the write-up of the BMI grid functions

I'm about halfway through the BMI grid functions. I added glossary
terms, references, and a new section to describe the different grid
types supported by BMI. All these things need more work before the
discussion of model grids is complete.

* Revise section on BMI grid functions

* Minor formatting changes

* Add navigation links after each BMI function

This should make it easier to browse sections and return to the
main BMI heading.

* Display BMI language specs and examples in a table

The table replaces a cumbersome pair of bulleted lists.

* Complete revision of model grids section

* Update links and document title

* Replace examples link with link to CSDMS homepage

* Complete BMI best practices section

* Remove the beta modifier from the version

Co-authored-by: Michael Galloy <[email protected]>

AUTHORS.rst

@@ -12,6 +12,8 @@ Contributors
 ------------
 
 * Richard Barnes
+* Michael Galloy
+* Julian Hofer
 * Eric Hutton
 * Boyana Norris
 * Scott Peckham

README.rst

@@ -29,38 +29,84 @@
 
    <p align="center">
 
-   The Basic Model Interface (BMI) is a library specification to
-   simplify the coupling of models.
+   The Basic Model Interface (BMI) is a standardized set of functions
+   that allows coupling of models to models and models to data.
 
    </p>
 
-In order to simplify conversion of an existing model to a reusable,
-plug-and-play model component, the
-`Community Surface Dynamics Modeling System <https://csdms.colorado.edu>`_
-(CSDMS) has developed a simple
-interface called the *Basic Model Interface* or *BMI* that model
-developers are asked to implement.  Recall that in this
-context an *interface* is a named set of functions with prescribed
-function names, argument types and return types.  The BMI functions
-make the model *self-describing* and fully *controllable* by a
-modeling framework or application.
-
+The *Basic Model Interface* (BMI) is a library specification
+created by the `Community Surface Dynamics Modeling System`_ (CSDMS)
+to facilitate the conversion of a model or dataset
+into a reusable, plug-and-play component.
+Recall that, in this context, an interface is a named set of functions
+with prescribed arguments and return values.
+The BMI functions make a model self-describing and fully controllable
+by a modeling framework or application.
 By design, the BMI functions are straightforward to implement in
-any language and use only simple (universal) data types. While the
-CSDMS model coupling framework supports C, C++, Fortran, Java,
-and Python, a BMI can described for any language.  CSDMS
-provides example bindings for BMI in each of the above languages.
-
-Also by design, the BMI functions are *noninvasive*.  This means
-that a BMI-compliant model does not make any calls to other
+any language, using only simple data types from standard language libraries.
+Also by design, the BMI functions are noninvasive.
+This means that a model's BMI does not make calls to other
 components or tools and is not modified to use any
-framework-specific data structures. BMI therefore introduces no
-dependencies into a model and the model can still be used
-in a *stand-alone* manner.
-
-The most current development version is always available from our git repository:
-http://github.com/csdms/bmi.
-
-Please note that this project is released with a
-`Contributor Code of Conduct <./CODE-OF-CONDUCT.rst>`_.
-By participating in this project you agree to abide by its terms.
+framework-specific data structures. A BMI, therefore, introduces no
+dependencies into a model, so the model can still be used
+in a stand-alone manner.
+
+The BMI is expressed
+in the `Scientific Interface Definition Language`_ (SIDL)
+in the file `bmi.sidl <./bmi.sidl>`_.
+BMI specifications for four languages -- C, C++,
+Fortran (77, 90/95, 2003, 2008),
+and Python -- are derived from this SIDL file.
+For each language,
+links to the specification and an example implementation
+are listed in the table below.
+
+.. table::
+   :align: center
+   :widths: 10, 10, 15
+
+   ========  ==============  ======================
+   Language  Specification   Example implementation
+   ========  ==============  ======================
+   C         `bmi-c`_        `bmi-example-c`_
+   C++       `bmi-cxx`_      `bmi-example-cxx`_
+   Fortran   `bmi-fortran`_  `bmi-example-fortran`_
+   Python    `bmi-python`_   `bmi-example-python`_
+   ========  ==============  ======================
+
+Detailed instructions for building the specifications and examples
+are given at each link above.
+The specifications can also be installed through `conda`.
+
+.. code-block:: bash
+
+   $ conda install -c conda-forge bmi-c
+   $ conda install -c conda-forge bmi-cxx
+   $ conda install -c conda-forge bmi-fortran
+   $ conda install -c conda-forge bmipy
+
+While CSDMS currently supports the four languages listed above,
+a BMI can be written for any language.
+BMI is a community-driven standard;
+`contributions <CONTRIBUTING.rst>`_
+that follow the `contributor code of conduct <./CODE-OF-CONDUCT.rst>`_
+are welcomed,
+and are `acknowledged <./AUTHORS.rst>`_.
+BMI is open source software released under the `MIT License <./LICENSE>`_.
+
+*The Community Surface Dynamics Modeling System
+is supported by the National Science Foundation.*
+
+
+.. Links
+
+.. _Community Surface Dynamics Modeling System: https://csdms.colorado.edu
+.. _Scientific Interface Definition Language: http://dx.doi.org/10.1177/1094342011414036
+.. _bmi-c: https://github.com/csdms/bmi-c
+.. _bmi-cxx: https://github.com/csdms/bmi-cxx
+.. _bmi-fortran: https://github.com/csdms/bmi-fortran
+.. _bmi-python: https://github.com/csdms/bmi-python
+.. _bmi-example-c: https://github.com/csdms/bmi-example-c
+.. _bmi-example-cxx: https://github.com/csdms/bmi-example-cxx
+.. _bmi-example-fortran: https://github.com/csdms/bmi-example-fortran
+.. _bmi-example-python: https://github.com/csdms/bmi-example-python

bmi.sidl

@@ -1,7 +1,7 @@
 //
 // The Basic Model Interface (BMI)
 //
-package csdms version 2.0b0 {
+package csdms version 2.0 {
   interface bmi {
 
     // Initialize, run, finalize (IRF)

docs/source/_templates/links.html

@@ -1,7 +1,7 @@
 <h3>Useful Links</h3>
 <ul>
   <li><a href="https://github.com/csdms/bmi/">BMI @ GitHub</a></li>
-  <li><a href="https://github.com/csdms/bmi/tree/master/bindings">BMI examples</a></li>
-  <li><a href="https://github.com/csdms/bmi/issues">Issue tracker</a></li>
+  <li><a href="https://github.com/csdms/bmi/issues">BMI issue tracker</a></li>
+  <li><a href="https://csdms.colorado.edu">CSDMS homepage</a></li>
 </ul>