rust/libceed: add README.md in preparation for packaging

rust/libceed/README.md

@@ -0,0 +1,57 @@
+# libceed: efficient, extensible discretization
+
+This crate provides an interface to [libCEED](https://libceed.readthedocs.io),
+which is a performance-portable library for extensible element-based
+discretization for partial differential equations and related computational
+problems. The formulation is algebraic and intended to be lightweight and easy
+to incorporate in higher level abstractions. See the [libCEED user
+manual](https://libceed.readthedocs.io) for details on [interface
+concepts](https://libceed.readthedocs.io/en/latest/libCEEDapi/) and extensive
+examples.
+
+![libCEED operator decomposition](https://libceed.readthedocs.io/en/latest/_images/libCEED.png)
+
+## Usage
+
+To call libCEED from a Rust package, the following `Cargo.toml` can be used.
+```toml
+[dependencies]
+libceed = "0.8.0"
+```
+
+For a development version of the libCEED Rust bindings, use the following `Cargo.toml`.
+```toml
+[dependencies]
+libceed = { git = "https://github.com/CEED/libCEED", branch = "main" }
+```
+
+```rust
+extern crate libceed;
+
+fn main() {
+    let ceed = libceed::Ceed::init("/cpu/self/ref");
+    let xc = ceed.vector_from_slice(&[0., 0.5, 1.0]).unwrap();
+    let xs = xc.view();
+    assert_eq!(xs[..], [0., 0.5, 1.0]);
+}
+```
+
+This crate provides modules for each object, but they are usually created from
+the `Ceed` object as with the vector above. The resource string passed to
+`Ceed::init` is used to identify the "backend", which includes algorithmic
+strategies and hardware such as NVIDIA and AMD GPUs. See the [libCEED
+documentation](https://libceed.readthedocs.io/en/latest/gettingstarted/#backends)
+for more information on available backends.
+
+## Examples
+
+Examples of libCEED can be found in the [libCEED repository](https://github.com/CEED/libCEED) under the
+`examples/rust` directory.
+
+## License: BSD-2-Clause
+
+## Contributing
+
+The `libceed` crate is developed within the [libCEED
+repository](https://github.com/CEED/libCEED). See the [contributing
+guidelines](https://libceed.readthedocs.io/en/latest/CONTRIBUTING/) for details.

rust/libceed/src/lib.rs

@@ -14,49 +14,8 @@
 // software, applications, hardware, advanced system engineering and early
 // testbed platforms, in support of the nation's exascale computing imperative
 
-/*!
-
-This is the documentation for the high level libCEED Rust interface. See the
-[libCEED user manual](https://libceed.readthedocs.io) for details on the
-abstraction and extensive examples.
-
-libCEED is a low-level API for for the efficient high-order discretization methods
-developed by the ECP co-design Center for Efficient Exascale Discretizations (CEED).
-While our focus is on high-order finite elements, the approach is mostly algebraic
-and thus applicable to other discretizations in factored form.
-
-## Usage
-
-To call libCEED from a Rust package, the following `Cargo.toml` can be used.
-```toml
-[dependencies]
-libceed = "0.8.0"
-```
-
-For a development version of the libCEED Rust bindings, use the following `Cargo.toml`.
-```toml
-[dependencies]
-libceed = { git = "https://github.com/CEED/libCEED", branch = "main" }
-```
-
-```
-extern crate libceed;
-
-fn main() {
-    let ceed = libceed::Ceed::init("/cpu/self/ref");
-    let xc = ceed.vector_from_slice(&[0., 0.5, 1.0]).unwrap();
-    let xs = xc.view();
-    assert_eq!(xs[..], [0., 0.5, 1.0]);
-}
-```
-
-## Examples
-
-Examples of libCEED can be found in the [libCEED repository](https://github.com/CEED/libCEED) under the
-`examples/rust` directory.
-
-*/
-
+// Fenced `rust` code blocks included from README.md are executed as part of doctests.
+#![doc = include_str!("../README.md")]
 // -----------------------------------------------------------------------------
 // Exceptions
 // -----------------------------------------------------------------------------

rust/libceed/tests/version-numbers.rs

@@ -27,7 +27,7 @@ fn test_html_root_url() {
 #[test]
 fn test_doc_version() {
     version_sync::assert_contains_regex!(
-        get_rel_path("src/lib.rs").to_str().unwrap(),
+        get_rel_path("README.md").to_str().unwrap(),
         "{name} = \"{version}\""
     );
 }