Skip to content

Commit ebae871

Browse files
rustyconoverclaude
rustyconover
and
claude
committed
Use snippet includes for doc examples, fix CI workflow
Replace copy-pasted code in docs with pymdownx.snippets includes from real source files (single source of truth). Create quick_example.cpp and getting_started.cpp as compiled examples for intro pages. Fix CI: install newer bison on macOS for thrift, correct vgi-rpc-python.git clone URL. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 0208bbe commit ebae871

10 files changed

Lines changed: 106 additions & 309 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# © Copyright 2025-2026, Query.Farm LLC - https://query.farm
2-
# SPDX-License-Identifier: Apache-2.0
3-
1+
# © Copyright 2025-2026, Query.Farm LLC - https://query.farm
2+
# SPDX-License-Identifier: Apache-2.0
3+
44
name: CI
55

66
on:
@@ -47,6 +47,12 @@ jobs:
4747
git -C vcpkg checkout 05442024c3fda64320bd25d2251cc9807b84fb6f
4848
./vcpkg/bootstrap-vcpkg.sh -disableMetrics
4949
50+
- name: Install newer bison (macOS)
51+
if: runner.os == 'macOS'
52+
run: |
53+
brew install bison
54+
echo "$(brew --prefix bison)/bin" >> $GITHUB_PATH
55+
5056
- name: Configure
5157
run: cmake --preset default
5258

@@ -76,7 +82,7 @@ jobs:
7682

7783
- name: Clone vgi-rpc (Python)
7884
if: matrix.conformance
79-
run: git clone https://github.com/Query-farm/vgi-rpc.git ../vgi-rpc
85+
run: git clone https://github.com/Query-farm/vgi-rpc-python.git ../vgi-rpc
8086

8187
- name: Test (conformance)
8288
if: matrix.conformance

‎docs/examples/calculator.md‎

Lines changed: 1 addition & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -3,76 +3,7 @@
33
A server with multiple unary methods demonstrating logging and error handling.
44

55
```cpp title="examples/calculator.cpp"
6-
#include <vgi_rpc/server.h>
7-
#include <vgi_rpc/request.h>
8-
#include <vgi_rpc/result.h>
9-
#include <vgi_rpc/call_context.h>
10-
#include <vgi_rpc/log.h>
11-
#include <vgi_rpc/arrow_utils.h>
12-
13-
#include <arrow/array/builder_primitive.h>
14-
#include <arrow/type.h>
15-
16-
#include <stdexcept>
17-
18-
namespace {
19-
20-
auto params_ab() {
21-
return arrow::schema({
22-
arrow::field("a", arrow::float64()),
23-
arrow::field("b", arrow::float64()),
24-
});
25-
}
26-
27-
auto result_double() {
28-
return arrow::schema({
29-
arrow::field("result", arrow::float64()),
30-
});
31-
}
32-
33-
vgi_rpc::Result make_double_result(double value) {
34-
arrow::DoubleBuilder builder;
35-
VGI_RPC_THROW_NOT_OK(builder.Append(value));
36-
auto array = vgi_rpc::unwrap(builder.Finish());
37-
return vgi_rpc::Result::value(result_double(), {array});
38-
}
39-
40-
} // anonymous namespace
41-
42-
int main() {
43-
auto server = vgi_rpc::ServerBuilder()
44-
.add_unary("add", params_ab(), result_double(),
45-
[](const vgi_rpc::Request& req, vgi_rpc::CallContext& ctx) {
46-
double a = req.get<double>("a");
47-
double b = req.get<double>("b");
48-
ctx.client_log(vgi_rpc::LogLevel::DEBUG,
49-
"Computing " + std::to_string(a) + " + " + std::to_string(b));
50-
return make_double_result(a + b);
51-
},
52-
"Add two numbers.")
53-
.add_unary("multiply", params_ab(), result_double(),
54-
[](const vgi_rpc::Request& req, vgi_rpc::CallContext& ctx) {
55-
double a = req.get<double>("a");
56-
double b = req.get<double>("b");
57-
return make_double_result(a * b);
58-
},
59-
"Multiply two numbers.")
60-
.add_unary("divide", params_ab(), result_double(),
61-
[](const vgi_rpc::Request& req, vgi_rpc::CallContext& ctx) {
62-
double a = req.get<double>("a");
63-
double b = req.get<double>("b");
64-
if (b == 0.0) {
65-
throw std::runtime_error("division by zero");
66-
}
67-
return make_double_result(a / b);
68-
},
69-
"Divide a by b. Raises error if b is zero.")
70-
.enable_describe("Calculator")
71-
.build();
72-
73-
server->run();
74-
return 0;
75-
}
6+
--8<-- "examples/calculator.cpp"
767
```
778

789
## Key Concepts

‎docs/examples/hello-world.md‎

Lines changed: 1 addition & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -3,46 +3,7 @@
33
The simplest possible vgi-rpc server: a single unary method that adds two numbers.
44

55
```cpp title="examples/hello_world.cpp"
6-
#include <vgi_rpc/server.h>
7-
#include <vgi_rpc/request.h>
8-
#include <vgi_rpc/result.h>
9-
#include <vgi_rpc/arrow_utils.h>
10-
11-
#include <arrow/array/builder_primitive.h>
12-
#include <arrow/type.h>
13-
14-
int main() {
15-
auto params_schema = arrow::schema({
16-
arrow::field("a", arrow::float64()),
17-
arrow::field("b", arrow::float64()),
18-
});
19-
20-
auto result_schema = arrow::schema({
21-
arrow::field("result", arrow::float64()),
22-
});
23-
24-
auto server = vgi_rpc::ServerBuilder()
25-
.add_unary("add", params_schema, result_schema,
26-
[](const vgi_rpc::Request& req, vgi_rpc::CallContext& ctx) {
27-
double a = req.get<double>("a");
28-
double b = req.get<double>("b");
29-
double sum = a + b;
30-
31-
arrow::DoubleBuilder builder;
32-
VGI_RPC_THROW_NOT_OK(builder.Append(sum));
33-
auto array = vgi_rpc::unwrap(builder.Finish());
34-
35-
return vgi_rpc::Result::value(
36-
arrow::schema({arrow::field("result", arrow::float64())}),
37-
{array});
38-
},
39-
"Add two numbers together.")
40-
.enable_describe("HelloWorld")
41-
.build();
42-
43-
server->run();
44-
return 0;
45-
}
6+
--8<-- "examples/hello_world.cpp"
467
```
478

489
## Key Concepts

‎docs/examples/streaming.md‎

Lines changed: 1 addition & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -3,124 +3,7 @@
33
Producer and exchange stream examples demonstrating stateful batch-oriented data processing.
44

55
```cpp title="examples/streaming.cpp"
6-
#include "vgi_rpc/server.h"
7-
#include "vgi_rpc/stream.h"
8-
#include "vgi_rpc/metadata.h"
9-
#include "vgi_rpc/arrow_utils.h"
10-
11-
#include <arrow/array.h>
12-
#include <arrow/builder.h>
13-
#include <arrow/type.h>
14-
15-
using namespace vgi_rpc;
16-
17-
// --- Counter producer: emits {index, value} batches ---
18-
19-
static auto counter_schema() {
20-
return arrow::schema({
21-
arrow::field("index", arrow::int64()),
22-
arrow::field("value", arrow::int64()),
23-
});
24-
}
25-
26-
class CounterState : public ProducerState {
27-
public:
28-
CounterState(int64_t count) : count_(count) {}
29-
30-
void produce(OutputCollector& out, CallContext& /*ctx*/) override {
31-
if (current_ >= count_) {
32-
out.finish();
33-
return;
34-
}
35-
36-
arrow::Int64Builder idx_builder, val_builder;
37-
VGI_RPC_THROW_NOT_OK(idx_builder.Append(current_));
38-
VGI_RPC_THROW_NOT_OK(val_builder.Append(current_ * 10));
39-
40-
auto idx_arr = unwrap(idx_builder.Finish());
41-
auto val_arr = unwrap(val_builder.Finish());
42-
43-
out.emit_arrays({idx_arr, val_arr});
44-
++current_;
45-
}
46-
47-
private:
48-
int64_t count_;
49-
int64_t current_ = 0;
50-
};
51-
52-
static Stream make_counter(const Request& req, CallContext& /*ctx*/) {
53-
auto count = req.get<int64_t>("count");
54-
55-
Stream s;
56-
s.output_schema = counter_schema();
57-
s.input_schema = empty_schema();
58-
s.state = std::make_shared<CounterState>(count);
59-
return s;
60-
}
61-
62-
// --- Scale exchange: multiplies input values by factor ---
63-
64-
static auto scale_input_schema() {
65-
return arrow::schema({arrow::field("value", arrow::float64())});
66-
}
67-
68-
static auto scale_output_schema() {
69-
return arrow::schema({arrow::field("value", arrow::float64())});
70-
}
71-
72-
class ScaleState : public ExchangeState {
73-
public:
74-
ScaleState(double factor) : factor_(factor) {}
75-
76-
void exchange(const AnnotatedBatch& input,
77-
OutputCollector& out, CallContext& /*ctx*/) override {
78-
auto col = std::static_pointer_cast<arrow::DoubleArray>(
79-
input.batch->column(0));
80-
81-
arrow::DoubleBuilder builder;
82-
for (int64_t i = 0; i < col->length(); ++i) {
83-
VGI_RPC_THROW_NOT_OK(builder.Append(col->Value(i) * factor_));
84-
}
85-
auto result_arr = unwrap(builder.Finish());
86-
out.emit_arrays({result_arr});
87-
}
88-
89-
private:
90-
double factor_;
91-
};
92-
93-
static Stream make_scale(const Request& req, CallContext& /*ctx*/) {
94-
auto factor = req.get<double>("factor");
95-
96-
Stream s;
97-
s.output_schema = scale_output_schema();
98-
s.input_schema = scale_input_schema();
99-
s.state = std::make_shared<ScaleState>(factor);
100-
return s;
101-
}
102-
103-
int main() {
104-
auto server = ServerBuilder()
105-
.add_producer(
106-
"produce_n",
107-
arrow::schema({arrow::field("count", arrow::int64())}),
108-
counter_schema(),
109-
make_counter,
110-
"Produce N batches with index and value=index*10")
111-
.add_exchange(
112-
"exchange_scale",
113-
arrow::schema({arrow::field("factor", arrow::float64())}),
114-
scale_input_schema(),
115-
scale_output_schema(),
116-
make_scale,
117-
"Scale input values by a factor")
118-
.enable_describe("StreamingExample")
119-
.build();
120-
121-
server->run();
122-
return 0;
123-
}
6+
--8<-- "examples/streaming.cpp"
1247
```
1258

1269
## Producer Pattern

‎docs/getting-started.md‎

Lines changed: 2 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -81,45 +81,8 @@ g++ -std=c++20 my_server.cpp $(pkg-config --cflags --libs vgi_rpc)
8181

8282
Create a minimal server with a single unary method:
8383

84-
```cpp
85-
#include <vgi_rpc/server.h>
86-
#include <vgi_rpc/request.h>
87-
#include <vgi_rpc/result.h>
88-
#include <vgi_rpc/arrow_utils.h>
89-
90-
#include <arrow/array/builder_primitive.h>
91-
#include <arrow/type.h>
92-
93-
int main() {
94-
auto params = arrow::schema({
95-
arrow::field("a", arrow::float64()),
96-
arrow::field("b", arrow::float64()),
97-
});
98-
auto result = arrow::schema({
99-
arrow::field("result", arrow::float64()),
100-
});
101-
102-
auto server = vgi_rpc::ServerBuilder()
103-
.add_unary("add", params, result,
104-
[](const vgi_rpc::Request& req, vgi_rpc::CallContext& ctx) {
105-
double a = req.get<double>("a");
106-
double b = req.get<double>("b");
107-
108-
arrow::DoubleBuilder builder;
109-
VGI_RPC_THROW_NOT_OK(builder.Append(a + b));
110-
auto array = vgi_rpc::unwrap(builder.Finish());
111-
112-
return vgi_rpc::Result::value(
113-
arrow::schema({arrow::field("result", arrow::float64())}),
114-
{array});
115-
},
116-
"Add two numbers.")
117-
.enable_describe("MyServer")
118-
.build();
119-
120-
server->run();
121-
return 0;
122-
}
84+
```cpp title="examples/getting_started.cpp"
85+
--8<-- "examples/getting_started.cpp"
12386
```
12487

12588
The server reads Arrow IPC requests from stdin and writes responses to stdout. Use `enable_describe()` to register the built-in `__describe__` introspection method, which lets clients discover available methods and their schemas.

‎docs/index.md‎

Lines changed: 2 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -14,41 +14,8 @@ The framework is single-threaded by design, processing one request at a time. Me
1414

1515
## Quick Example
1616

17-
```cpp
18-
#include <vgi_rpc/server.h>
19-
#include <vgi_rpc/request.h>
20-
#include <vgi_rpc/result.h>
21-
#include <vgi_rpc/arrow_utils.h>
22-
23-
#include <arrow/array/builder_primitive.h>
24-
#include <arrow/type.h>
25-
26-
int main() {
27-
auto server = vgi_rpc::ServerBuilder()
28-
.add_unary("add",
29-
arrow::schema({
30-
arrow::field("a", arrow::float64()),
31-
arrow::field("b", arrow::float64()),
32-
}),
33-
arrow::schema({arrow::field("result", arrow::float64())}),
34-
[](const vgi_rpc::Request& req, vgi_rpc::CallContext& ctx) {
35-
double a = req.get<double>("a");
36-
double b = req.get<double>("b");
37-
38-
arrow::DoubleBuilder builder;
39-
VGI_RPC_THROW_NOT_OK(builder.Append(a + b));
40-
auto array = vgi_rpc::unwrap(builder.Finish());
41-
42-
return vgi_rpc::Result::value(
43-
arrow::schema({arrow::field("result", arrow::float64())}),
44-
{array});
45-
},
46-
"Add two numbers together.")
47-
.enable_describe("MyServer")
48-
.build();
49-
50-
server->run();
51-
}
17+
```cpp title="examples/quick_example.cpp"
18+
--8<-- "examples/quick_example.cpp"
5219
```
5320

5421
## Features

‎examples/CMakeLists.txt‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# © Copyright 2025-2026, Query.Farm LLC - https://query.farm
2-
# SPDX-License-Identifier: Apache-2.0
3-
1+
# © Copyright 2025-2026, Query.Farm LLC - https://query.farm
2+
# SPDX-License-Identifier: Apache-2.0
3+
44
add_executable(hello_world hello_world.cpp)
55
target_link_libraries(hello_world PRIVATE vgi_rpc)
66

@@ -9,3 +9,9 @@ target_link_libraries(calculator PRIVATE vgi_rpc)
99

1010
add_executable(streaming streaming.cpp)
1111
target_link_libraries(streaming PRIVATE vgi_rpc)
12+
13+
add_executable(quick_example quick_example.cpp)
14+
target_link_libraries(quick_example PRIVATE vgi_rpc)
15+
16+
add_executable(getting_started getting_started.cpp)
17+
target_link_libraries(getting_started PRIVATE vgi_rpc)

0 commit comments

Comments
 (0)