alamb commented on code in PR #7956:
URL: https://github.com/apache/arrow-datafusion/pull/7956#discussion_r1375424046
##########
docs/README.md:
##########
@@ -53,6 +60,25 @@ To make changes to the docs, simply make a Pull Request with
your
proposed changes as normal. When the PR is merged the docs will be
automatically updated.
+## Including Source Code
+
+We want to make sure that all source code in the documentation is tested as
part of the build and release process. We
Review Comment:
I wonder if you considered the opposite:
Leaving the code example inlined in the documentation, and extracting it out
to `datafusion-docs-test` with a script.
This would have the benefit that the markdown would be closer to the actual
output documentation, and it might be easier to work on the examples inline.
The downside is that then we would need to somehow run a script to copy the
examples into datafusion-docs-tests as part of CI to make sure they were up to
date
##########
docs/source/library-user-guide/building-logical-plans.md:
##########
@@ -36,35 +36,7 @@ much easier to use the [LogicalPlanBuilder], which is
described in the next sect
Here is an example of building a logical plan directly:
-<!-- source for this example is in
datafusion_docs::library_logical_plan::plan_1 -->
-
-```rust
-// create a logical table source
-let schema = Schema::new(vec![
- Field::new("id", DataType::Int32, true),
- Field::new("name", DataType::Utf8, true),
-]);
-let table_source = LogicalTableSource::new(SchemaRef::new(schema));
-
-// create a TableScan plan
-let projection = None; // optional projection
-let filters = vec![]; // optional filters to push down
-let fetch = None; // optional LIMIT
-let table_scan = LogicalPlan::TableScan(TableScan::try_new(
- "person",
- Arc::new(table_source),
- projection,
- filters,
- fetch,
-)?);
-
-// create a Filter plan that evaluates `id > 500` that wraps the TableScan
-let filter_expr = col("id").gt(lit(500));
-let plan = LogicalPlan::Filter(Filter::try_new(filter_expr,
Arc::new(table_scan))?);
-
-// print the plan
-println!("{}", plan.display_indent_schema());
-```
+<!-- include: library_logical_plan::create_plan -->
Review Comment:
I tested what happens if there is a bad link to an example here:
```diff
$ git diff
diff --git a/docs/source/library-user-guide/building-logical-plans.md
b/docs/source/library-user-guide/building-logical-plans.md
index b75a788e83..6ae376d445 100644
--- a/docs/source/library-user-guide/building-logical-plans.md
+++ b/docs/source/library-user-guide/building-logical-plans.md
@@ -36,7 +36,7 @@ much easier to use the [LogicalPlanBuilder], which is
described in the next sect
Here is an example of building a logical plan directly:
-<!-- include: library_logical_plan::create_plan -->
+<!-- include: library_logical_plan::create_planXXXXX -->
This example produces the following plan:
```
It seems to just leave a blank in the docs
Is there any way to generate an error in this case instead?
##########
docs/build.sh:
##########
@@ -21,8 +21,14 @@
set -e
rm -rf build 2> /dev/null
rm -rf temp 2> /dev/null
+
+# copy source to temp dir
Review Comment:
There is also a `build.bat` file in this directory that might need to get
updated
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
