Add documentation for prepare statements.

[dhegberg]

Which issue does this PR close?

• Partially addresses Document PREPARE statements #13570 .

Rationale for this change

Add basic documentation for SQL PREPARE and the handling in Datafusion. Named variables will be documented when .sql() support is implemented.

What changes are included in this PR?

Just documentation

Are these changes tested?

Just auto-builds.

Are there any user-facing changes?

No

[alamb]

Thank you for this @dhegberg ❤️

I rendered it locally and it looks quite nice 👌 This is a great addition. Thank you so much

I

[alamb]

In order to test that the doc examples run (and thus that they compile and remain working) we need to add an entry to core/src/lib.rs like this:

diff --git a/datafusion/core/src/lib.rs b/datafusion/core/src/lib.rs
index 48ee8e46b..70b595442 100644
--- a/datafusion/core/src/lib.rs
+++ b/datafusion/core/src/lib.rs
@@ -962,6 +962,12 @@ doc_comment::doctest!(
     user_guide_sql_operators
 );

+#[cfg(doctest)]
+doc_comment::doctest!(
+    "../../../docs/source/user-guide/sql/prepared_statements.md",
+    user_guide_prepared_statements
+);
+
 #[cfg(doctest)]
 doc_comment::doctest!(
     "../../../docs/source/user-guide/sql/scalar_functions.md",

Then you can run the doc tests like this:

cargo test --doc -p datafusion -- prepared_statement

Since I had the code checked out anyways I went ahead and pushed the code to test the examples (and make those tests pass) to this PR

[alamb]

Thanks again @dhegberg