This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new 1840ab5331 Document how to test examples in user guide, add some more
coverage (#11178)
1840ab5331 is described below
commit 1840ab5331391d278de55d2bfb9a019c93314427
Author: Andrew Lamb <[email protected]>
AuthorDate: Tue Jul 2 12:22:02 2024 -0400
Document how to test examples in user guide, add some more coverage (#11178)
* Document testing examples, add some more coverage
* add docs
---
datafusion/core/src/lib.rs | 41 +++++++++++++++++++++++++++++++-
docs/source/contributor-guide/testing.md | 25 +++++++++++++++++++
docs/source/user-guide/expressions.md | 4 +++-
3 files changed, 68 insertions(+), 2 deletions(-)
diff --git a/datafusion/core/src/lib.rs b/datafusion/core/src/lib.rs
index d81efaf68c..5f0af2d0ad 100644
--- a/datafusion/core/src/lib.rs
+++ b/datafusion/core/src/lib.rs
@@ -587,8 +587,47 @@ pub mod test_util;
#[cfg(doctest)]
doc_comment::doctest!("../../../README.md", readme_example_test);
+// Instructions for Documentation Examples
+//
+// The following commands test the examples from the user guide as part of
+// `cargo test --doc`
+//
+// # Adding new tests:
+//
+// Simply add code like this to your .md file and ensure your md file is
+// included in the lists below.
+//
+// ```rust
+// <code here will be tested>
+// ```
+//
+// Note that sometimes it helps to author the doctest as a standalone program
+// first, and then copy it into the user guide.
+//
+// # Debugging Test Failures
+//
+// Unfortunately, the line numbers reported by doctest do not correspond to the
+// line numbers of in the .md files. Thus, if a doctest fails, use the name of
+// the test to find the relevant file in the list below, and then find the
+// example in that file to fix.
+//
+// For example, if `user_guide_expressions(line 123)` fails,
+// go to `docs/source/user-guide/expressions.md` to find the relevant problem.
+
#[cfg(doctest)]
doc_comment::doctest!(
"../../../docs/source/user-guide/example-usage.md",
- user_guid_example_tests
+ user_guide_example_usage
+);
+
+#[cfg(doctest)]
+doc_comment::doctest!(
+ "../../../docs/source/user-guide/configs.md",
+ user_guide_configs
+);
+
+#[cfg(doctest)]
+doc_comment::doctest!(
+ "../../../docs/source/user-guide/expressions.md",
+ user_guide_expressions
);
diff --git a/docs/source/contributor-guide/testing.md
b/docs/source/contributor-guide/testing.md
index 11f53bcb2a..018cc6233c 100644
--- a/docs/source/contributor-guide/testing.md
+++ b/docs/source/contributor-guide/testing.md
@@ -49,6 +49,31 @@ You can run these tests individually using `cargo` as normal
command such as
cargo test -p datafusion --test parquet_exec
```
+## Documentation Examples
+
+We use Rust [doctest] to verify examples from the documentation are correct and
+up-to-date. These tests are run as part of our CI and you can run them them
+locally with the following command:
+
+```shell
+cargo test --doc
+```
+
+### API Documentation Examples
+
+As with other Rust projects, examples in doc comments in `.rs` files are
+automatically checked to ensure they work and evolve along with the code.
+
+### User Guide Documentation
+
+Rust example code from the user guide (anything marked with \`\`\`rust) is also
+tested in the same way using the [doc_comment] crate. See the end of
+[core/src/lib.rs] for more details.
+
+[doctest]: https://doc.rust-lang.org/rust-by-example/testing/doc_testing.html
+[doc_comment]: https://docs.rs/doc-comment/latest/doc_comment
+[core/src/lib.rs]:
https://github.com/apache/datafusion/blob/main/datafusion/core/src/lib.rs#L583
+
## Benchmarks
### Criterion Benchmarks
diff --git a/docs/source/user-guide/expressions.md
b/docs/source/user-guide/expressions.md
index cae9627210..6e693a0e70 100644
--- a/docs/source/user-guide/expressions.md
+++ b/docs/source/user-guide/expressions.md
@@ -26,8 +26,10 @@ available for creating logical expressions. These are
documented below.
Most functions and methods may receive and return an `Expr`, which can be
chained together using a fluent-style API:
```rust
+use datafusion::prelude::*;
// create the expression `(a > 6) AND (b < 7)`
-col("a").gt(lit(6)).and(col("b").lt(lit(7)))
+col("a").gt(lit(6)).and(col("b").lt(lit(7)));
+
```
:::
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
