Skip to content

Run / Test all examples in Documentation #14435

@alamb

Description

@alamb

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

// 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions