Updated extending operators documentation

[the0ninjas]

Which issue does this PR close?

• Closes IDEA: Use one of the examples from Datafusion Blog 45 to complete custom logical plans/execution plans page #15422

What changes are included in this PR?

• Updated the documentation page using the uwheel example based on the the blog example Blog: DataFusion @ UWheel by @Max-Meldrum

[the0ninjas]

@alamb - Since I'm first-time contributor, could you help trigger the CI please?

[Max-Meldrum]

Seems like it is actually trying to compile the doctest code. If this isn't required then perhaps a no_run is in order?

[alamb]

Seems like it is actually trying to compile the doctest code. If this isn't required then perhaps a no_run is in order?

Yes, we run all the examples in the doc tests -- instructions for doing so locally are here

datafusion/datafusion/core/src/lib.rs

Lines 836 to 861 in 784df33

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

The idea is to ensure that the examples in the docs do not drift apart from reality

[alamb]

Thank you for this contribution @the0ninjas and the hints @Max-Meldrum

I am marking the PR as draft while we work on getting the CI passing. Then please mark it ready for review again!

[Max-Meldrum]

Seems like it is actually trying to compile the doctest code. If this isn't required then perhaps a no_run is in order?

Yes, we run all the examples in the doc tests -- instructions for doing so locally are here

datafusion/datafusion/core/src/lib.rs

Lines 836 to 861 in 784df33

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

The idea is to ensure that the examples in the docs do not drift apart from reality

Right, I see. The current example code is using stuff that is external to the Datafusion repo and is over at datafusion-uwheel.

For instance the try_rewrite function. What could be a good approach here?

[alamb]

For instance the try_rewrite function. What could be a good approach here?

One idea could be to bring some simplified version of this to the doc example, or maybe leave a link to the other repository

[alamb]

Another alternate to make the doc tests pass is to comment the code out, using

# /*
...
*/

For example, see

• Add DataFusion 47.0.0 Upgrade Guide #15749

[Max-Meldrum]

@the0ninjas

It should passes the test if ```rust,ignore is used instead. And we could link a reference to the external code https://github.com/uwheel/datafusion-uwheel

[Max-Meldrum]

I believe this PR is now ready to be merged @alamb

[alamb]

Thank you @the0ninjas and @Max-Meldrum -- this is a very nice addition to the docs

[alamb]

Thanks again @Max-Meldrum @edmondop and @the0ninjas