Simplify README, move content to documentation

CREDITS.rst

@@ -1,6 +1,13 @@
 Credits
 =======
 
-* Eric Hutton
+Development Leads
+-----------------
 
-* Mark Piper
+- `Eric Hutton <https://github.com/mcflugen>`_
+- `Mark Piper <https://github.com/mdpiper>`_
+
+Contributors
+------------
+
+- `Sam Harrison <https://github.com/samharrison7>`_

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",

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 <https://github.com/csdms/babelizer/tree/develop/external/tests>`_
+directory of the *babelizer* repository.

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*

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*

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,15 +30,19 @@ 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
 ==========
 
 .. 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

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 .

docs/source/use.rst

@@ -0,0 +1,20 @@
+Using the *babelizer*
+=====================
+
+Given a completed *babelizer* :ref:`configuration file <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`.

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 <https://github.com/csdms/bmi-c/>`_
+  * `C++ specification <https://github.com/csdms/bmi-cxx/>`_
+  * `Fortran specification <https://github.com/csdms/bmi-fortran/>`_
+  * `Python specification <https://github.com/csdms/bmi-python/>`_
+
+* The following give examples of a BMI implementation for each of the supported languages:
+
+  * `C example <https://github.com/csdms/bmi-example-c/>`_
+  * `C++ example <https://github.com/csdms/bmi-example-cxx/>`_
+  * `Fortran example <https://github.com/csdms/bmi-example-fortran/>`_
+  * `Python example <https://github.com/csdms/bmi-example-python/>`_
+
+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/

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.

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"