From e62034344d1c4750036f687ed995e9c1383ab629 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 10 Apr 2024 11:34:36 -0600 Subject: [PATCH 01/20] Reformat author list; add contributors I followed the format of the Landlab AUTHORS.rst. --- CREDITS.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) 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 `_ From 8cbf67c985da689e198cbf236ae3ee0aef3f4314 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 10 Apr 2024 11:47:36 -0600 Subject: [PATCH 02/20] Point link to develop branch --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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" From bb491a1958dc45831f30007411a41e16317af185 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 10 Apr 2024 14:21:52 -0600 Subject: [PATCH 03/20] Strip shell prompt symbol from commands This makes it easier to copy-paste the commands. --- README.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 9b801179..d7edbde8 100644 --- a/README.rst +++ b/README.rst @@ -120,8 +120,8 @@ base Python installation. This can be done with *conda*: .. code:: bash - $ conda create -n babelizer python=3 - $ conda activate babelizer + conda create -n babelizer python=3 + conda activate babelizer Stable Release ^^^^^^^^^^^^^^ @@ -130,7 +130,7 @@ The *babelizer* and its dependencies are best installed with *conda*: .. code:: bash - $ conda install babelizer -c conda-forge + conda install babelizer -c conda-forge From Source ^^^^^^^^^^^ @@ -141,13 +141,13 @@ install *babelizer* into the current environment: .. code:: bash - $ pip install -e . + pip install -e . or using *conda*: .. code:: bash - $ conda install --file=requirements.txt -c conda-forge + conda install --file=requirements.txt -c conda-forge Input file @@ -194,7 +194,7 @@ For example, the above *babel.toml* was generated with: .. code:: bash - $ babelize generate > babel.toml + babelize generate > babel.toml Library section ^^^^^^^^^^^^^^^ @@ -402,7 +402,7 @@ the above *babel.toml* can be generated with the following, .. code:: bash - babelize sample-config + babelize sample-config Use --- @@ -412,7 +412,7 @@ sending output to the current directory .. code:: bash - babelize init babel.toml + babelize init babel.toml Update an existing repository From 5c4675f2f7ea1c48e39d381718fcefabdca4e7ab Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 10 Apr 2024 14:25:03 -0600 Subject: [PATCH 04/20] Remove conda instructions from source install This fixes #99. --- README.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/README.rst b/README.rst index d7edbde8..f3a9664f 100644 --- a/README.rst +++ b/README.rst @@ -143,12 +143,6 @@ install *babelizer* into the current environment: pip install -e . -or using *conda*: - -.. code:: bash - - conda install --file=requirements.txt -c conda-forge - Input file ---------- From 6c52e8767bbc46c2078bb76f96c5775df73dc551 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 10 Apr 2024 14:31:55 -0600 Subject: [PATCH 05/20] Rename 'input file' to 'configuration file' --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index f3a9664f..cf01701a 100644 --- a/README.rst +++ b/README.rst @@ -144,10 +144,10 @@ install *babelizer* into the current environment: pip install -e . -Input file ----------- +Configuration file +------------------ -The *babelizer* requires a single *toml*-formatted input file that describes +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 blank *babel.toml* file: From 014a5a6fdfe67ea23bacfe473ac2d2c055cf31eb Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 10 Apr 2024 14:34:44 -0600 Subject: [PATCH 06/20] Add a link to the full documentation This fixes #98. --- README.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.rst b/README.rst index cf01701a..0193f284 100644 --- a/README.rst +++ b/README.rst @@ -32,6 +32,9 @@ Supported languages include: * Fortran * Python +Full documentation for the *babelizer*, including examples, +can be found at https://babelizer.readthedocs.io/. + The Babelizer is part of the CSDMS Workbench -------------------------------------------- From c0ed06feafdc3bb682c69cc0abb86614dc00acde Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 10 Apr 2024 15:15:32 -0600 Subject: [PATCH 07/20] Tweak section comments in sample config file --- babelizer/cli.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) 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", From 831408b947cb2e20ef63ae2e7f9e0d996e5b72ba Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 10 Apr 2024 15:19:39 -0600 Subject: [PATCH 08/20] Replace 'generate' command with 'sample-config'; update output --- README.rst | 81 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 31 deletions(-) diff --git a/README.rst b/README.rst index 0193f284..b130d3d2 100644 --- a/README.rst +++ b/README.rst @@ -156,42 +156,61 @@ 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 = [] + # See https://babelizer.readthedocs.io/ for more information - [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. + # 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 generate > babel.toml + babelize sample-config > babel.toml Library section ^^^^^^^^^^^^^^^ From fc82657879e5d7d4cb6c05bc80d8f47be7b53b19 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Wed, 10 Apr 2024 16:23:47 -0600 Subject: [PATCH 09/20] Update decriptions of the babelizer configuration file --- README.rst | 81 +++++++++++++++++++----------------------------------- 1 file changed, 28 insertions(+), 53 deletions(-) diff --git a/README.rst b/README.rst index b130d3d2..76faf8a5 100644 --- a/README.rst +++ b/README.rst @@ -215,12 +215,13 @@ For example, the above *babel.toml* was generated with: Library section ^^^^^^^^^^^^^^^ -The *library* section specifies information about the library being babelized. +The *library* section provides information about the library being *babelized*. Name """" -The name of the babelized class. +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. @@ -230,17 +231,12 @@ 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*. +for example, use "bmimonorail" for a library *libbmimonorail.a*. Header """""" @@ -257,24 +253,22 @@ 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 +An example of a C++ library (*bmi_child*), exposing a class *BmiChild* (that 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" + [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 +whereas a C library (*bmi_cem*), exposing a function *register_bmi_cem* (that implements a BMI) might look like: .. code:: toml - [library] [library.Cem] language = "c" library = "bmi_cem" @@ -284,30 +278,23 @@ implements a BMI) might look like: Build section ^^^^^^^^^^^^^ -In the build section the user can specify flags to pass to the compiler +In the *build* section, specify flags to pass to the compiler when building the extension. Package section ^^^^^^^^^^^^^^^ -Name and extra requirements needed to build the babelized library. +The *package* section provides the 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" +The name to use for the Python package output from the *babelizer*. Requirements """""""""""" -List of packages required by the library being wrapped. For example, the +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. @@ -349,18 +336,11 @@ Summary A short description of the wrapped library. -Ci section +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 """""""""""""" @@ -369,20 +349,19 @@ 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 +A list of operating systems on which to build the generated project. Supported values are *linux*, *mac*, and *windows*. -Example babel.toml -^^^^^^^^^^^^^^^^^^ +Example configuration file +^^^^^^^^^^^^^^^^^^^^^^^^^^ -Below is an example of a *babel.toml* file that describes a shared library, +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] [library.Hydrotrend] language = "c" library = "bmi_hydrotrend" @@ -405,25 +384,21 @@ called *hydrotrend*. github_username = "pymt-lab" package_author = "csdms" package_author_email = "csdms@colorado.edu" - package_license = "MIT" + package_license = "MIT License" summary = "PyMT plugin for hydrotrend" [ci] - python_version = ["3.7", "3.8", "3.9"] + python_version = ["3.10", "3.11", "3.12"] 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, - -.. code:: bash - - babelize sample-config +For other examples of *babelizer* configuration files, +see the directories under the `external/tests `_ +directory of the *babelizer* repository. Use --- -Generate Python bindings for a library that implements a BMI, +Generate a Python package for a library that implements a BMI, sending output to the current directory .. code:: bash @@ -436,8 +411,8 @@ Update an existing repository babelize update -For a complete example of using the *babelizer* -to wrap a C library exposing a BMI, +For complete examples of using the *babelizer* +to wrap C and Fortran libraries exposing a BMI, see the User Guide of the `documentation`_. From de0de8fc5f2a6033c67c4f02ae8225c676a382f4 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Apr 2024 13:00:27 -0600 Subject: [PATCH 10/20] Remove the included readme from the docs --- docs/source/readme.rst | 1 - 1 file changed, 1 deletion(-) delete mode 100644 docs/source/readme.rst 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 From 1bf6d16061635e83863630805b81a1565341e302 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Apr 2024 13:12:40 -0600 Subject: [PATCH 11/20] Move install instructions from README to docs Keep a stub section in the README pointing to the docs. --- README.rst | 52 +++++----------------------------------- docs/source/index.rst | 4 +--- docs/source/install.rst | 53 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 60 insertions(+), 49 deletions(-) create mode 100644 docs/source/install.rst diff --git a/README.rst b/README.rst index 76faf8a5..7f58b577 100644 --- a/README.rst +++ b/README.rst @@ -93,59 +93,18 @@ 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*. - - 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: +The quickest way to install the *babelizer* is with *conda*: .. code:: bash - pip install -e . + conda install -c conda-forge babelizer +For more detailed information, +including how to install the *babelizer* from source, +see the `installation instructions`_ in the documentation. Configuration file ------------------ @@ -429,3 +388,4 @@ see the User Guide of the `documentation`_. .. _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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 0a025055..8509d469 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,14 +30,13 @@ 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 ========== .. toctree:: :maxdepth: 2 - readme + install cli example-c example-fortran 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 . From 8badd0acddc554e81a31b8aa6cec707e85b5f457 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Apr 2024 13:25:06 -0600 Subject: [PATCH 12/20] Move "should I use the babelizer?" section to docs --- README.rst | 43 ------------------------------------------- docs/source/index.rst | 1 + docs/source/why.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 41 insertions(+), 43 deletions(-) create mode 100644 docs/source/why.rst diff --git a/README.rst b/README.rst index 7f58b577..2cc3c1f9 100644 --- a/README.rst +++ b/README.rst @@ -50,49 +50,6 @@ 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. - Installation ------------ diff --git a/docs/source/index.rst b/docs/source/index.rst index 8509d469..26992551 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -36,6 +36,7 @@ User Guide .. toctree:: :maxdepth: 2 + why install cli example-c 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/ From 0a773eb2bc10876a7dc9eb83749074610cbce1fe Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Apr 2024 13:38:26 -0600 Subject: [PATCH 13/20] Move configuration file section to docs --- README.rst | 248 ---------------------------------- docs/source/configuration.rst | 247 +++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 3 files changed, 248 insertions(+), 248 deletions(-) create mode 100644 docs/source/configuration.rst diff --git a/README.rst b/README.rst index 2cc3c1f9..907460b3 100644 --- a/README.rst +++ b/README.rst @@ -63,254 +63,6 @@ For more detailed information, including how to install the *babelizer* from source, see the `installation instructions`_ in the documentation. -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 blank *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. - Use --- diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 00000000..79ba09d7 --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,247 @@ +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/index.rst b/docs/source/index.rst index 26992551..df02278c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -39,6 +39,7 @@ User Guide why install cli + configuration example-c example-fortran glossary From 436ca1c04610e3c8c0e372b692a88e85b9be1b2a Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Apr 2024 14:04:33 -0600 Subject: [PATCH 14/20] Add cross-referencing headings --- docs/source/configuration.rst | 2 ++ docs/source/example-c.rst | 2 ++ docs/source/example-fortran.rst | 2 ++ 3 files changed, 6 insertions(+) diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 79ba09d7..971a3497 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -1,3 +1,5 @@ +.. _configuration-file: + Configuration file ================== diff --git a/docs/source/example-c.rst b/docs/source/example-c.rst index ebdf256c..9687a038 100644 --- a/docs/source/example-c.rst +++ b/docs/source/example-c.rst @@ -1,3 +1,5 @@ +.. _example-c: + Example: Wrapping a C model =========================== diff --git a/docs/source/example-fortran.rst b/docs/source/example-fortran.rst index 0d2c3c56..45d0e4f6 100644 --- a/docs/source/example-fortran.rst +++ b/docs/source/example-fortran.rst @@ -1,3 +1,5 @@ +.. _example-fortran: + Example: Wrapping a Fortran model ================================= From b2753ea9ae91dc8bef9144fb8b9acdaeba32ccc7 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Apr 2024 14:05:29 -0600 Subject: [PATCH 15/20] Move use section from README to docs --- README.rst | 21 --------------------- docs/source/index.rst | 1 + docs/source/use.rst | 20 ++++++++++++++++++++ 3 files changed, 21 insertions(+), 21 deletions(-) create mode 100644 docs/source/use.rst diff --git a/README.rst b/README.rst index 907460b3..ec4bfa0c 100644 --- a/README.rst +++ b/README.rst @@ -63,27 +63,6 @@ For more detailed information, including how to install the *babelizer* from source, see the `installation instructions`_ in the documentation. -Use ---- - -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 complete examples of using the *babelizer* -to wrap C and Fortran libraries exposing a BMI, -see the User Guide of the `documentation`_. - - .. Links: .. _Basic Model Interface: https://bmi.readthedocs.io/ diff --git a/docs/source/index.rst b/docs/source/index.rst index df02278c..69e9eea6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -40,6 +40,7 @@ User Guide install cli configuration + use example-c example-fortran glossary 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`. From 777141e5e337f13409b577a84c98439268b7d8bf Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Apr 2024 14:51:57 -0600 Subject: [PATCH 16/20] Add contributing and acknowledgments sections to README --- README.rst | 55 +++++++++++++++++++++++++----------------------------- 1 file changed, 25 insertions(+), 30 deletions(-) diff --git a/README.rst b/README.rst index ec4bfa0c..096e1c08 100644 --- a/README.rst +++ b/README.rst @@ -11,9 +11,6 @@ :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 @@ -21,9 +18,10 @@ 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,23 +30,12 @@ Supported languages include: * Fortran * Python -Full documentation for the *babelizer*, including examples, -can be found at https://babelizer.readthedocs.io/. - - -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. +for building and coupling models. + +Full documentation for the *babelizer*, including examples, +can be found at https://babelizer.readthedocs.io/. Installation ------------ @@ -63,17 +50,25 @@ For more detailed information, including how to install the *babelizer* from source, see the `installation instructions`_ in the documentation. +Contributing +------------ + +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`_. + +Acknowledgments +--------------- + +The Community Surface Dynamics Modeling System is funded +by the U.S. National Science Foundation. + .. Links: +.. _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 From be1f4187a9b5e9eabb8d27de59b630d8cdeaba11 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Apr 2024 17:22:37 -0600 Subject: [PATCH 17/20] Tidy status badges --- README.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 096e1c08..aa203fb4 100644 --- a/README.rst +++ b/README.rst @@ -1,19 +1,4 @@ -.. 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://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 ====================================================== @@ -66,6 +51,21 @@ 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 From e85364934f416efda7e273efb1f36c718022abbc Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Thu, 11 Apr 2024 17:30:22 -0600 Subject: [PATCH 18/20] Add news fragment --- docs/source/index.rst | 2 ++ news/100.doc | 3 +++ 2 files changed, 5 insertions(+) create mode 100644 news/100.doc diff --git a/docs/source/index.rst b/docs/source/index.rst index 69e9eea6..c712de9c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,6 +30,8 @@ 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 ========== 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. From d8d07a2fdaef1cf81912c066eb2c7ec41280776e Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Fri, 12 Apr 2024 11:38:42 -0600 Subject: [PATCH 19/20] Use rtfd.io links for products --- docs/source/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index c712de9c..26a09fa9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -99,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 From 6c43e571fc6db23344a27c720fadd6af8825135f Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Fri, 12 Apr 2024 14:04:12 -0600 Subject: [PATCH 20/20] Update links to configuration file section of docs --- docs/source/example-c.rst | 2 +- docs/source/example-fortran.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/example-c.rst b/docs/source/example-c.rst index 9687a038..294b4696 100644 --- a/docs/source/example-c.rst +++ b/docs/source/example-c.rst @@ -156,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 45d0e4f6..4fed9439 100644 --- a/docs/source/example-fortran.rst +++ b/docs/source/example-fortran.rst @@ -185,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*