-
Notifications
You must be signed in to change notification settings - Fork 1.7k
Description
Is your feature request related to a problem or challenge?
The https://datafusion.apache.org/library-user-guide/index.html has some great examples ❤
However, not all of these examples are actually tested during CI which results in issues like this one found (and fixed!) by @nuno-faria
It is possible to prevent this type of problem by testing the examples automatically, following the instructions here
datafusion/datafusion/core/src/lib.rs
Lines 819 to 844 in 67bc04c
| // 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. |
Describe the solution you'd like
I would like to test all examples in the entire User Guide and Library User Guide.
Here are the files in the docs/source/library-user-guide directory. The ones that are not checked do not have their examples checked yet
-
docs/source/library-user-guide/adding-udfs.md -
docs/source/library-user-guide/api-health.md -
docs/source/library-user-guide/building-logical-plans.md -
docs/source/library-user-guide/catalogs.md -
docs/source/library-user-guide/custom-table-providers.md -
docs/source/library-user-guide/extending-operators.md -
docs/source/library-user-guide/extensions.md -
docs/source/library-user-guide/index.md -
docs/source/library-user-guide/profiling.md -
docs/source/library-user-guide/query-optimizer.md -
docs/source/library-user-guide/using-the-dataframe-api.md -
docs/source/library-user-guide/using-the-sql-api.md -
docs/source/library-user-guide/working-with-exprs.md
Describe alternatives you've considered
To test the examples on a particular page, such as adding-udfs.md
Step 1: Add entry to lib.rs
andrewlamb@Andrews-MacBook-Pro-2:~/Software/datafusion$ git diff
diff --git a/datafusion/core/src/lib.rs b/datafusion/core/src/lib.rs
index 780b22983..509ef601c 100644
--- a/datafusion/core/src/lib.rs
+++ b/datafusion/core/src/lib.rs
@@ -873,6 +873,12 @@ doc_comment::doctest!(
user_guide_expressions
);
+#[cfg(doctest)]
+doc_comment::doctest!(
+ "../../../docs/source/library-user-guide/adding-udfs.md",
+ library_user_guide_adding_udfs
+);
+
#[cfg(doctest)]
doc_comment::doctest!(
"../../../docs/source/library-user-guide/using-the-sql-api.md",Step 2: Run tests:
cargo test --doc -- library_user_guide_adding_udfs
Step 3: Fix issues / run again
(iterate and repeat until test passes)
Additional context
No response