From a1cbad85bd2cf51a2e81228682bd7ae54f5d0f99 Mon Sep 17 00:00:00 2001
From: Jed Brown <jed@jedbrown.org>
Date: Fri, 28 May 2021 09:50:32 -0600
Subject: [PATCH] rust/libceed: add README.md in preparation for packaging

---
 rust/libceed/README.md                | 57 +++++++++++++++++++++++++++
 rust/libceed/src/lib.rs               | 45 +--------------------
 rust/libceed/tests/version-numbers.rs |  2 +-
 3 files changed, 60 insertions(+), 44 deletions(-)
 create mode 100644 rust/libceed/README.md

diff --git a/rust/libceed/README.md b/rust/libceed/README.md
new file mode 100644
index 0000000000..1f93315730
--- /dev/null
+++ b/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.
diff --git a/rust/libceed/src/lib.rs b/rust/libceed/src/lib.rs
index 33e723997e..6eff21f61b 100755
--- a/rust/libceed/src/lib.rs
+++ b/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
 // -----------------------------------------------------------------------------
diff --git a/rust/libceed/tests/version-numbers.rs b/rust/libceed/tests/version-numbers.rs
index c085bb06d5..afb9d3112a 100644
--- a/rust/libceed/tests/version-numbers.rs
+++ b/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}\""
     );
 }