diff --git a/CREDITS.rst b/CREDITS.rst index 2e879ef5..c3518373 100644 --- a/CREDITS.rst +++ b/CREDITS.rst @@ -1,6 +1,13 @@ Credits ======= -* Eric Hutton +Development Leads +----------------- -* Mark Piper +- `Eric Hutton `_ +- `Mark Piper `_ + +Contributors +------------ + +- `Sam Harrison `_ diff --git a/README.rst b/README.rst index 9b801179..aa203fb4 100644 --- a/README.rst +++ b/README.rst @@ -1,29 +1,12 @@ -.. image:: https://joss.theoj.org/papers/10.21105/joss.03344/status.svg - :target: https://doi.org/10.21105/joss.03344 - -.. image:: https://github.com/csdms/babelizer/workflows/Build/Test%20CI/badge.svg - :target: https://github.com/csdms/babelizer/actions?query=workflow%3A%22Build%2FTest+CI%22 - -.. image:: https://anaconda.org/conda-forge/babelizer/badges/version.svg - :target: https://anaconda.org/conda-forge/babelizer - -.. image:: https://readthedocs.org/projects/babelizer/badge/?version=latest - :target: https://babelizer.readthedocs.io/en/latest/?badge=latest - :alt: Documentation Status - -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/csdms/babelizer - -.. image:: https://coveralls.io/repos/github/csdms/babelizer/badge.svg?branch=develop - :target: https://coveralls.io/github/csdms/babelizer?branch=develop - +|JOSS paper| |Build Status| |Conda Version| |Documentation Status| |Coverage Status| The Babelizer: Wrap BMI libraries with Python bindings ====================================================== - -The *babelizer* is a utility for wrapping a library that exposes a `Basic Model Interface`_ (BMI) so that it can be -imported as a Python package. +The *babelizer* is an open source Python utility, +developed by the `Community Surface Dynamics Modeling System`_ (CSDMS), +for wrapping a library that exposes a `Basic Model Interface`_ (BMI) +so that it can be imported as a Python package. Supported languages include: @@ -32,409 +15,60 @@ Supported languages include: * Fortran * Python - -The Babelizer is part of the CSDMS Workbench --------------------------------------------- - The *babelizer* is an element of the `CSDMS Workbench`_, an integrated system of software tools, technologies, and standards -for building and coupling models. The Workbench provides two Python -frameworks for model coupling, *pymt* and *landlab*. -The *babelizer* was written to bring models written in other languages into -these frameworks. -However, as long as your model -satisfies the requirements below, you can use the *babelizer* -to bring your model into Python without having to use any of the -other tools in the Workbench. - - -Should I use the babelizer? ---------------------------- - -To determine if the -*babelizer* is right for you, first be aware of a few requirements. - -1. Your model must be written in C, C++, Fortran, or Python -2. Your model must provide a shared library -3. Your model must expose a `Basic Model Interface`_ through this library - -The most difficult of the three requirements is the last--implementing a BMI. This -involves adding a series of functions with prescribed names, -arguments, and return values for querying and controlling your model. We have created -several resources to help you understand the BMI and to guide you -through the implementation process. - -BMI resources -^^^^^^^^^^^^^ - -* The `Basic Model Interface`_ documentation provides an overview of the BMI as well - as a detailed description of all of the BMI functions. -* The following provide a BMI specification for each of the supported languages: - - * `C spec `_ - * `C++ spec `_ - * `Fortran spec `_ - * `Python spec `_ - -* The following give examples of a BMI implementation for each of the supported languages: - - * `C example `_ - * `C++ example `_ - * `Fortran example `_ - * `Python example `_ - -Note -^^^^ - -There are lots of other good reasons to create a BMI for -your model--not just so you can bring it into Python with the *babelizer*! -Read all about them in the `Basic Model Interface`_ documentation. - - -Requirements ------------- - -The *babelizer* requires Python >=3.10. - - -Apart from Python, the *babelizer* has a number of other requirements, all of which -can be obtained through either *pip* or *conda*, that will be automatically -installed when you install the *babelizer*. - -To see a full listing of the requirements, have a look at the project's -*requirements.txt* file. - -If you are a developer of the *babelizer* you will also want to install -additional dependencies for running the *babelizer*'s tests to make sure -that things are working as they should. These dependencies are listed -in *requirements-testing.txt*. +for building and coupling models. +Full documentation for the *babelizer*, including examples, +can be found at https://babelizer.readthedocs.io/. Installation ------------ -To install the *babelizer*, first create a new environment. -Although this isn't strictly necessary, it -isolates the installation to avoid conflicts with your -base Python installation. This can be done with *conda*: - -.. code:: bash - - $ conda create -n babelizer python=3 - $ conda activate babelizer - -Stable Release -^^^^^^^^^^^^^^ - -The *babelizer* and its dependencies are best installed with *conda*: - -.. code:: bash - - $ conda install babelizer -c conda-forge - -From Source -^^^^^^^^^^^ - -After downloading the the *babelizer* source code, run the following from -*babelizer*'s top-level directory (the one that contains *setup.py*) to -install *babelizer* into the current environment: - -.. code:: bash - - $ pip install -e . - -or using *conda*: - -.. code:: bash - - $ conda install --file=requirements.txt -c conda-forge - - -Input file ----------- - -The *babelizer* requires a single *toml*-formatted input file that describes -the library to wrap. This file is typically named *babel.toml*. -An example of a blank *babel.toml* file: - -.. code:: toml - - [library] - [library.""] - language = "c" - library = "" - header = "" - entry_point = "" - - [build] - undef_macros = [] - define_macros = [] - libraries = [] - library_dirs = [] - include_dirs = [] - extra_compile_args = [] - - [package] - name = "" - requirements = [] - - [info] - github_username = "pymt-lab" - package_author = "csdms" - package_author_email = "csdms@colorado.edu" - package_license = "MIT" - summary = "" - - [ci] - python_version = ["3.9"] - os = ["linux", "mac", "windows"] - -You can generate *babel.toml* files using the *babelize generate* command. -For example, the above *babel.toml* was generated with: - -.. code:: bash - - $ babelize generate > babel.toml - -Library section -^^^^^^^^^^^^^^^ - -The *library* section specifies information about the library being babelized. - -Name -"""" - -The name of the babelized class. -This will be a Python class, -so it should follow Python naming conventions such as camel-case typing. - -Language -"""""""" - -The programming language of the library (possible values are "c", "c++", -"fortran", and "python"). - -.. code:: toml - - [library] - language = "c" - -Library -""""""" - -The name of the BMI library to wrap. -This is the text passed to the linker through the `-l` option; -for example, use "foo" for a library *libfoo.a*. - -Header -"""""" - -The name of the header file (*.h*, *.hxx*) declaring the BMI class. -This option is only needed when wrapping C and C++ libraries. - -Entry point -""""""""""" - -The name of the BMI entry point into the library. -For object-oriented languages, -this is typically the name of a class that implements the BMI. -For procedural languages, -this is typically a function. - -An example of a C++ library (*bmi_child*), exposing a class *BmiChild* (which -implements a BMI) might look like the following: - -.. code:: toml - - [library] - [library.Child] - language = "c++" - library = "bmi_child" - header = "bmi_child.hxx" - entry_point = "BmiChild" - -whereas a C library (*bmi_cem*), exposing a function *register_bmi_cem* (which -implements a BMI) might look like: - -.. code:: toml - - [library] - [library.Cem] - language = "c" - library = "bmi_cem" - header = "bmi_cem.h" - entry_point = "register_bmi_cem" - -Build section -^^^^^^^^^^^^^ - -In the build section the user can specify flags to pass to the compiler -when building the extension. - -Package section -^^^^^^^^^^^^^^^ - -Name and extra requirements needed to build the babelized library. - -Name -"""" - -Name to use for the wrapped package. This is used when creating the new -package **. For example, the following will create -a new package, *pymt_foo*. - -.. code:: toml - - [package] - name = "pymt_foo" - -Requirements -"""""""""""" - -List of packages required by the library being wrapped. For example, the -following indicates that the packages *foo* and *bar* are dependencies -for the package. - -.. code:: toml - - [package] - requirements = [ "foo", "bar",] - -Info section -^^^^^^^^^^^^ - -Descriptive information about the package. - -Github username -""""""""""""""" - -The GitHub username or organization where this package will be hosted. This -is used in generating links to the CI, docs, etc. - -Author -"""""" - -Author of the wrapped package. Note that this is not the author of the -library being wrapped, just the code generated by the *babelizer*. - -Email -""""" - -Contact email to use for the wrapped package. - -License -""""""" - -Specify the Open Source license for the wrapped package. Note that this is not the -license for the library being wrapped, just for the code generated by the *babelizer*. - -Summary -""""""" - -A short description of the wrapped library. - -Ci section -^^^^^^^^^^ - -Information about how to set up continuous integration. - -.. code:: toml - - [ci] - python_version = ["3.7", "3.8", "3.9"] - os = ["linux", "mac", "windows"] - - -Python version -"""""""""""""" - -A list of Python versions to build and test the generated project with. - -Operating system -"""""""""""""""" - -A list of operating systems to build the generate project on. Supported values are -*linux*, *mac*, and *windows*. - -Example babel.toml -^^^^^^^^^^^^^^^^^^ - -Below is an example of a *babel.toml* file that describes a shared library, -written in C. In this example, the library, *bmi_hydrotrend*, exposes the -function *register_bmi_hydrotrend* that implements a BMI for a component -called *hydrotrend*. - -.. code:: toml - - [library] - [library.Hydrotrend] - language = "c" - library = "bmi_hydrotrend" - header = "bmi_hydrotrend.h" - entry_point = "register_bmi_hydrotrend" - - [build] - undef_macros = [] - define_macros = [] - libraries = [] - library_dirs = [] - include_dirs = [] - extra_compile_args = [] - - [package] - name = "pymt_hydrotrend" - requirements = ["hydrotrend"] - - [info] - github_username = "pymt-lab" - package_author = "csdms" - package_author_email = "csdms@colorado.edu" - package_license = "MIT" - summary = "PyMT plugin for hydrotrend" - - [ci] - python_version = ["3.7", "3.8", "3.9"] - os = ["linux", "mac", "windows"] - -You can use the ``babelize sample-config`` command to generate -a sample *babel.toml* file to get you started. For example, -the above *babel.toml* can be generated with the following, +The quickest way to install the *babelizer* is with *conda*: .. code:: bash - babelize sample-config - -Use ---- + conda install -c conda-forge babelizer -Generate Python bindings for a library that implements a BMI, -sending output to the current directory - -.. code:: bash +For more detailed information, +including how to install the *babelizer* from source, +see the `installation instructions`_ in the documentation. - babelize init babel.toml - -Update an existing repository - -.. code:: bash +Contributing +------------ - babelize update +If you wish to report bugs or request new features for the *babelizer*, +or if you would like to fix bugs and implement new features, +please see our `contributing`_ guidelines. +Contributions to the *babelizer* are `credited`_. -For a complete example of using the *babelizer* -to wrap a C library exposing a BMI, -see the User Guide of the `documentation`_. +Acknowledgments +--------------- +The Community Surface Dynamics Modeling System is funded +by the U.S. National Science Foundation. .. Links: +.. |JOSS paper| image:: https://joss.theoj.org/papers/10.21105/joss.03344/status.svg + :target: https://doi.org/10.21105/joss.03344 + :alt: JOSS paper +.. |Build Status| image:: https://github.com/csdms/babelizer/workflows/Build/Test%20CI/badge.svg + :target: https://github.com/csdms/babelizer/actions?query=workflow%3A%22Build%2FTest+CI%22 + :alt: Build status +.. |Conda Version| image:: https://anaconda.org/conda-forge/babelizer/badges/version.svg + :target: https://anaconda.org/conda-forge/babelizer + :alt: Conda version +.. |Documentation Status| image:: https://readthedocs.org/projects/babelizer/badge/?version=latest + :target: https://babelizer.readthedocs.io/en/latest/?badge=latest + :alt: Documentation status +.. |Coverage Status| image:: https://coveralls.io/repos/github/csdms/babelizer/badge.svg?branch=develop + :target: https://coveralls.io/github/csdms/babelizer?branch=develop + :alt: Coverage status +.. _Community Surface Dynamics Modeling System: https://csdms.colorado.edu .. _Basic Model Interface: https://bmi.readthedocs.io/ .. _CSDMS Workbench: https://csdms.colorado.edu/wiki/Workbench -.. _documentation: https://babelizer.readthedocs.io/ -.. _BMI C: https://github.com/csdms/bmi-c/ -.. _BMI C++: 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 C++: 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/ +.. _installation instructions: https://babelizer.readthedocs.io/en/latest/install.html +.. _contributing: https://babelizer.readthedocs.io/en/latest/contributing.html +.. _credited: https://babelizer.readthedocs.io/en/latest/credits.html diff --git a/babelizer/cli.py b/babelizer/cli.py index 029f191d..f686f7cf 100644 --- a/babelizer/cli.py +++ b/babelizer/cli.py @@ -332,8 +332,7 @@ def _generated_files( header = "monorail.h" entry_point = "register_monorail" -# Describe compiler options need to build the library being -# wrapped. +# Describe compiler options to build the library being wrapped. [build] undef_macros = [] define_macros = [] @@ -347,6 +346,7 @@ def _generated_files( name = "springfield_monorail" requirements = ["three_million_dollars"] +# Provide author and package information. [info] github_username = "lyle-lanley" package_author = "Lyle Lanley" @@ -358,6 +358,7 @@ def _generated_files( Monorail! What's it called? Monorail! That's right! Monorail! ''' +# Set continuous integration options. [ci] python_version = [ "3.10", diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 00000000..971a3497 --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,249 @@ +.. _configuration-file: + +Configuration file +================== + +The *babelizer* requires a single *toml*-formatted configuration file +that describes the library to wrap. +This file is typically named ``babel.toml``. +An example of a ``babel.toml`` file: + +.. code:: toml + + # See https://babelizer.readthedocs.io/ for more information + + # Describe the library being wrapped. + [library.Monorail] + language = "c" + library = "bmimonorail" + header = "monorail.h" + entry_point = "register_monorail" + + # Describe compiler options to build the library being wrapped. + [build] + undef_macros = [] + define_macros = [] + libraries = [] + library_dirs = [] + include_dirs = [] + extra_compile_args = [] + + # Describe the newly wrapped package. + [package] + name = "springfield_monorail" + requirements = ["three_million_dollars"] + + # Provide author and package information. + [info] + github_username = "lyle-lanley" + package_author = "Lyle Lanley" + package_author_email = "lyle@monorail.com" + package_license = "MIT License" + summary = ''' + Well, sir, there's nothing on Earth like a genuine, + bona fide, electrified, six-car monorail. What'd I say? + Monorail! What's it called? Monorail! That's right! Monorail! + ''' + + # Set continuous integration options. + [ci] + python_version = [ + "3.10", + "3.11", + "3.12", + ] + os = [ + "linux", + "mac", + "windows", + ] + +You can generate *babelizer* configuration files using the ``babelize sample-config`` command. +For example, the above ``babel.toml`` was generated with: + +.. code:: bash + + babelize sample-config > babel.toml + +Library section +--------------- + +The *library* section provides information about the library being *babelized*. + +Name +"""" + +The name of the *babelized* class is integrated into the *library* table header; +in the example above, ``Monorail``. +This will be a Python class, +so it should follow Python naming conventions such as camel-case typing. + +Language +"""""""" + +The programming language of the library (possible values are "c", "c++", +"fortran", and "python"). + +Library +""""""" + +The name of the BMI library to wrap. +This is the text passed to the linker through the `-l` option; +for example, use "bmimonorail" for a library ``libbmimonorail.a``. + +Header +"""""" + +The name of the header file (``.h``, ``.hxx``) declaring the BMI class. +This option is only needed when wrapping C and C++ libraries. + +Entry point +""""""""""" + +The name of the BMI entry point into the library. +For object-oriented languages, +this is typically the name of a class that implements the BMI. +For procedural languages, +this is typically a function. + +An example of a C++ library (*bmi_child*), exposing a class *BmiChild* (that +implements a BMI) might look like the following: + +.. code:: toml + + [library.Child] + language = "c++" + library = "bmi_child" + header = "bmi_child.hxx" + entry_point = "BmiChild" + +whereas a C library (*bmi_cem*), exposing a function *register_bmi_cem* (that +implements a BMI) might look like: + +.. code:: toml + + [library.Cem] + language = "c" + library = "bmi_cem" + header = "bmi_cem.h" + entry_point = "register_bmi_cem" + +Build section +------------- + +In the *build* section, specify flags to pass to the compiler +when building the extension. + +Package section +--------------- + +The *package* section provides the name and extra requirements needed to build the *babelized* library. + +Name +"""" + +The name to use for the Python package output from the *babelizer*. + +Requirements +"""""""""""" + +A list of packages required by the library being wrapped. For example, the +following indicates that the packages *foo* and *bar* are dependencies +for the package. + +.. code:: toml + + [package] + requirements = [ "foo", "bar",] + +Info section +------------ + +Descriptive information about the package. + +Github username +""""""""""""""" + +The GitHub username or organization where this package will be hosted. This +is used in generating links to the CI, docs, etc. + +Author +"""""" + +Author of the wrapped package. Note that this is not the author of the +library being wrapped, just the code generated by the *babelizer*. + +Email +""""" + +Contact email to use for the wrapped package. + +License +""""""" + +Specify the Open Source license for the wrapped package. Note that this is not the +license for the library being wrapped, just for the code generated by the *babelizer*. + +Summary +""""""" + +A short description of the wrapped library. + +CI section +---------- + +Information about how to set up continuous integration. + +Python version +"""""""""""""" + +A list of Python versions to build and test the generated project with. + +Operating system +"""""""""""""""" + +A list of operating systems on which to build the generated project. Supported values are +*linux*, *mac*, and *windows*. + +Example configuration file +-------------------------- + +Below is an example of a *babelizer* configuration file that describes a shared library, +written in C. In this example, the library, *bmi_hydrotrend*, exposes the +function *register_bmi_hydrotrend* that implements a BMI for a component +called *hydrotrend*. + +.. code:: toml + + [library.Hydrotrend] + language = "c" + library = "bmi_hydrotrend" + header = "bmi_hydrotrend.h" + entry_point = "register_bmi_hydrotrend" + + [build] + undef_macros = [] + define_macros = [] + libraries = [] + library_dirs = [] + include_dirs = [] + extra_compile_args = [] + + [package] + name = "pymt_hydrotrend" + requirements = ["hydrotrend"] + + [info] + github_username = "pymt-lab" + package_author = "csdms" + package_author_email = "csdms@colorado.edu" + package_license = "MIT License" + summary = "PyMT plugin for hydrotrend" + + [ci] + python_version = ["3.10", "3.11", "3.12"] + os = ["linux", "mac", "windows"] + +For other examples of *babelizer* configuration files, +see the directories under the `external/tests `_ +directory of the *babelizer* repository. diff --git a/docs/source/example-c.rst b/docs/source/example-c.rst index ebdf256c..294b4696 100644 --- a/docs/source/example-c.rst +++ b/docs/source/example-c.rst @@ -1,3 +1,5 @@ +.. _example-c: + Example: Wrapping a C model =========================== @@ -154,7 +156,7 @@ The configuration file looks like this: :literal: For more information on the entries and sections of the *babelizer* configuration file, -see `Input file <./readme.html#input-file>`_. +see `Configuration file <./configuration.html>`_. Wrap the model with the *babelizer* diff --git a/docs/source/example-fortran.rst b/docs/source/example-fortran.rst index 0d2c3c56..4fed9439 100644 --- a/docs/source/example-fortran.rst +++ b/docs/source/example-fortran.rst @@ -1,3 +1,5 @@ +.. _example-fortran: + Example: Wrapping a Fortran model ================================= @@ -183,7 +185,7 @@ The configuration file looks like this: :literal: For more information on the entries and sections of the *babelizer* configuration file, -see `Input file <./readme.html#input-file>`_. +see `Configuration file <./configuration.html>`_. Wrap the model with the *babelizer* diff --git a/docs/source/index.rst b/docs/source/index.rst index 0a025055..26a09fa9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,7 +6,6 @@ .. title:: babelizer - The *babelizer* is an open source Python utility, developed by the `Community Surface Dynamics Modeling System`_ (CSDMS), for wrapping models that expose a `Basic Model Interface`_ (BMI) @@ -31,6 +30,7 @@ The *babelizer* is an element of the `CSDMS Workbench`_, an integrated system of software tools, technologies, and standards for building and coupling models. +.. _user-guide: User Guide ========== @@ -38,8 +38,11 @@ User Guide .. toctree:: :maxdepth: 2 - readme + why + install cli + configuration + use example-c example-fortran glossary @@ -96,9 +99,9 @@ Indices and tables Links .. _Community Surface Dynamics Modeling System: https://csdms.colorado.edu -.. _Basic Model Interface: https://github.com/csdms/bmi -.. _bmi-tester: https://github.com/csdms/bmi-tester +.. _Basic Model Interface: https://bmi.readthedocs.io/ +.. _bmi-tester: https://bmi-tester.readthedocs.io/ .. _pymt: https://pymt.readthedocs.io/ -.. _Landlab: https://landlab.github.io/ +.. _Landlab: https://landlab.readthedocs.io/ .. _CSDMS Workbench: https://csdms.colorado.edu/wiki/Workbench -.. _CSDMS Help Desk: https://github.com/csdms/help-desk +.. _CSDMS Help Desk: https://csdms.github.io/help-desk diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 00000000..97ed2f3c --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,53 @@ +Installation +============ + +To install the *babelizer*, first create a new environment. +Although this isn't strictly necessary, +it isolates the installation to avoid conflicts with your base Python installation. +This can be done with *conda*: + +.. code:: bash + + conda create -n babelizer python=3 + conda activate babelizer + +Requirements +------------ + +The *babelizer* requires Python >=3.10. + +Apart from Python, the *babelizer* has a number of other requirements, +all of which can be obtained through either *pip* or *conda*, +that will be automatically installed when you install the *babelizer*. + +To see a full listing of the requirements, +have a look at the project's ``requirements.txt`` file. + +If you are working with the source code of the *babelizer*, +you will also want to install additional dependencies +for testing, documentation, and development. +These dependencies are listed in the files + +* ``requirements-dev.txt`` +* ``requirements-docs.txt`` +* ``requirements-testing.txt`` + +Stable release +-------------- + +The *babelizer* and its dependencies are best installed with *conda*: + +.. code:: bash + + conda install -c conda-forge babelizer + +From source +----------- + +After downloading the the *babelizer* source code, +run *pip* from *babelizer*'s top-level directory (the one that contains *setup.py*) +to install *babelizer* into the current environment: + +.. code:: bash + + pip install -e . diff --git a/docs/source/readme.rst b/docs/source/readme.rst deleted file mode 100644 index a6210d3d..00000000 --- a/docs/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/docs/source/use.rst b/docs/source/use.rst new file mode 100644 index 00000000..4500a822 --- /dev/null +++ b/docs/source/use.rst @@ -0,0 +1,20 @@ +Using the *babelizer* +===================== + +Given a completed *babelizer* :ref:`configuration file `, +generate a Python package for a library that implements a BMI, +sending output to the current directory. + +.. code:: bash + + babelize init babel.toml + +Update an existing repository. + +.. code:: bash + + babelize update + +For in-depth examples of using the *babelizer* +to wrap libraries exposing a BMI, +see :ref:`example-c` and :ref:`example-fortran`. diff --git a/docs/source/why.rst b/docs/source/why.rst new file mode 100644 index 00000000..8fdb273f --- /dev/null +++ b/docs/source/why.rst @@ -0,0 +1,40 @@ +Should I use the *babelizer*? +============================= + +To determine if the *babelizer* is right for you, +first be aware of a few requirements. + +1. Your model must be written in C, C++, Fortran, or Python +2. Your model must provide a shared library +3. Your model must expose a `Basic Model Interface`_ (BMI) through this library + +The most difficult of the three requirements is the last--implementing a BMI. +This involves adding a series of functions with prescribed names, +arguments, and return values for querying and controlling your model. + +We have created several resources to help you understand the BMI and to guide you +through the implementation process. + +* The `Basic Model Interface`_ documentation provides an overview of the BMI as well + as a detailed description of all of the BMI functions. +* The following provide a BMI specification for each of the supported languages: + + * `C specification `_ + * `C++ specification `_ + * `Fortran specification `_ + * `Python specification `_ + +* The following give examples of a BMI implementation for each of the supported languages: + + * `C example `_ + * `C++ example `_ + * `Fortran example `_ + * `Python example `_ + +There are lots of other good reasons to create a BMI for +your model--not just so you can bring it into Python with the *babelizer*! +Read all about them in the `Basic Model Interface`_ documentation. + +.. Links: + +.. _Basic Model Interface: https://bmi.readthedocs.io/ diff --git a/news/100.doc b/news/100.doc new file mode 100644 index 00000000..00c1c2cc --- /dev/null +++ b/news/100.doc @@ -0,0 +1,3 @@ + +Simplified the project README file, moving much of its content into the +:ref:`user-guide` of the documentation. diff --git a/pyproject.toml b/pyproject.toml index cf527ac9..0ef037bf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,7 +50,7 @@ dynamic = [ text = "MIT" [project.urls] -changelog = "https://github.com/csdms/babelizer/blob/master/CHANGES.rst" +changelog = "https://github.com/csdms/babelizer/blob/develop/CHANGES.rst" documentation = "https://babelizer.readthedocs.io/" homepage = "https://babelizer.readthedocs.io/" repository = "https://github.com/csdms/babelizer"