Skip to content

Commit 7b1ddcf

Browse files
magnesjmagnesj
authored
Document proto files
* add proto files * generate doc from proto * Populate rst file from specified proto files * Generate doc from proto files in workflow file * Update rips module, proto files, and Python examples
1 parent 2ab54d1 commit 7b1ddcf

18 files changed

+2004
-6
lines changed

‎.github/workflows/update-from-latest.yml‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,36 @@ jobs:
6161
cp -r upstream_rips/rips*/rips ./docs/
6262
# ls -R ./docs/rips
6363
64+
- name: Download proto files from ResInsight repository
65+
run: |
66+
# Create proto directory
67+
mkdir -p docs/proto
68+
69+
# Get list of proto files from the GrpcProtos directory
70+
curl -H "Authorization: token ${{ secrets.PAT }}" \
71+
https://api.github.com/repos/OPM/ResInsight/contents/GrpcInterface/GrpcProtos?ref=dev \
72+
-o proto_files.json
73+
74+
# Download each proto file
75+
for file in $(jq -r '.[] | select(.name | endswith(".proto")) | .download_url' proto_files.json); do
76+
filename=$(basename "$file")
77+
echo "Downloading $filename"
78+
curl -H "Authorization: token ${{ secrets.PAT }}" \
79+
-L "$file" \
80+
-o "docs/proto/$filename"
81+
done
82+
83+
# Clean up
84+
rm proto_files.json
85+
86+
echo "Proto files downloaded:"
87+
ls -la docs/proto/
88+
89+
- name: Generate Protocol Buffer documentation
90+
run: |
91+
cd docs/source
92+
python generate_protobuf_docs.py --config proto_docs_config.json
93+
6494
- name: Create Read the Docs Python examples
6595
run: |
6696
cd docs/source
@@ -69,7 +99,7 @@ jobs:
6999
- uses: peter-evans/create-pull-request@v7
70100
with:
71101
token: ${{ secrets.GITHUB_TOKEN }}
72-
commit-message: "Update rips module and Python examples"
73-
title: "Automated fixes of rips from ResInsight artifacts"
102+
commit-message: "Update rips module, proto files, and Python examples"
103+
title: "Automated updates from ResInsight repository"
74104
branch: artifact-update-rips
75105
branch-suffix: random

‎docs/README.md‎

Lines changed: 80 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
# ResInsight Scripting API - rips
22

33
## Update Procedure for `next-major-release` Branch
4-
The workflow **update-from-latest.yml** is used to update the documentation. This workflow runs the script `docs/source/create_python_examples.py`, downloads the latest rips package from the ResInsight main repository, builds the documentation, and creates a pull request in this repository if needed.
4+
The workflow **update-from-latest.yml** is used to update the documentation. This workflow:
5+
1. Downloads the latest rips package from the ResInsight main repository
6+
2. Downloads Protocol Buffer (.proto) files from the ResInsight repository
7+
3. Generates Protocol Buffer documentation using `docs/source/generate_protobuf_docs.py`
8+
4. Generates Python examples using `docs/source/create_python_examples.py`
9+
5. Creates a pull request in this repository if needed
510

611
## Conventions
712
We use an internal system to communicate large binary structures between Python and ResInsight. Functions related to this system are postfixed with `_internal` and are removed from the generated documentation using the script `clean_internal_methods.py`.
@@ -21,12 +26,83 @@ We use an internal system to communicate large binary structures between Python
2126
```sh
2227
pip install m2r2 sphinx_rtd_theme sphinx-automodapi
2328
```
24-
6. Open a command line in the **docs** folder
25-
7. Run:
29+
6. **(Optional)** If you have proto files in `docs/proto/`, generate Protocol Buffer documentation:
30+
```sh
31+
cd docs/source
32+
python generate_protobuf_docs.py
33+
cd ..
34+
```
35+
7. Open a command line in the **docs** folder
36+
8. Run:
2637
```sh
2738
sphinx-build -b html source build
2839
```
29-
8. Open the generated documentation in your browser from `build/html/index.html`
40+
9. Open the generated documentation in your browser from `build/html/index.html`
41+
42+
## Updating Protocol Buffer Documentation
43+
The Protocol Buffer documentation is automatically generated from `.proto` files:
44+
45+
### Automatic Updates (via GitHub Actions)
46+
The workflow automatically:
47+
- Downloads the latest `.proto` files from ResInsight repository
48+
- Generates `ProtobufStructures.rst` documentation
49+
- Includes it in pull requests
50+
51+
### Manual Updates
52+
To manually update Protocol Buffer documentation:
53+
54+
1. Ensure proto files exist in `docs/proto/` directory
55+
2. Run the generator script:
56+
```sh
57+
cd docs/source
58+
python generate_protobuf_docs.py
59+
```
60+
3. The script will update `docs/source/ProtobufStructures.rst` with current proto definitions
61+
62+
### Advanced Usage
63+
64+
The generator script supports filtering and configuration:
65+
66+
**Include specific proto files only:**
67+
```sh
68+
python generate_protobuf_docs.py --include SimulatorTables.proto Definitions.proto
69+
```
70+
71+
**Exclude specific proto files:**
72+
```sh
73+
python generate_protobuf_docs.py --exclude Internal.proto Debug.proto
74+
```
75+
76+
**Use a configuration file:**
77+
```sh
78+
python generate_protobuf_docs.py --config proto_docs_config.json
79+
```
80+
81+
**Configuration file format (JSON or YAML):**
82+
```json
83+
{
84+
"include": ["SimulatorTables.proto", "Definitions.proto"],
85+
"exclude": ["Internal.proto"],
86+
"important_messages": ["SimulatorTableData", "Vec3d"]
87+
}
88+
```
89+
90+
**Custom output location:**
91+
```sh
92+
python generate_protobuf_docs.py --output custom.rst --proto-dir /path/to/protos
93+
```
94+
95+
**Command-line help:**
96+
```sh
97+
python generate_protobuf_docs.py --help
98+
```
99+
100+
The generator script parses `.proto` files and creates RST documentation including:
101+
- Message definitions with field types and descriptions
102+
- Enum definitions
103+
- Service definitions (gRPC methods)
104+
- Cross-references to Python API methods
105+
- Highlighting of important/commonly-used structures
30106

31107
## Releasing to Master
32108
Create a pull request from `next-major-release` to the `master` branch.

‎docs/proto/App.proto‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
syntax = "proto3";
2+
3+
package rips;
4+
5+
import "Definitions.proto";
6+
import "PdmObject.proto";
7+
8+
service App {
9+
rpc GetVersion(Empty) returns (Version) {}
10+
rpc Exit(Empty) returns (Empty) {}
11+
rpc GetRuntimeInfo(Empty) returns (RuntimeInfo) {}
12+
rpc GetPdmObject(Empty) returns (PdmObject) {}
13+
}
14+
15+
message Version {
16+
int32 major_version = 1;
17+
int32 minor_version = 2;
18+
int32 patch_version = 3;
19+
}
20+
21+
enum ApplicationTypeEnum {
22+
GUI_APPLICATION = 0;
23+
CONSOLE_APPLICATION = 1;
24+
}
25+
26+
message RuntimeInfo { ApplicationTypeEnum app_type = 1; }

‎docs/proto/Case.proto‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
syntax = "proto3";
2+
3+
import "PdmObject.proto";
4+
import "Definitions.proto";
5+
6+
package rips;
7+
8+
service Case {
9+
rpc GetGridCount(CaseRequest) returns (GridCount) {}
10+
rpc GetCellCount(CellInfoRequest) returns (CellCount) {}
11+
rpc GetCellInfoForActiveCells(CellInfoRequest)
12+
returns (stream CellInfoArray) {}
13+
rpc GetCellCenterForActiveCells(CellInfoRequest)
14+
returns (stream CellCenters) {}
15+
rpc GetCellCornersForActiveCells(CellInfoRequest)
16+
returns (stream CellCornersArray) {}
17+
rpc GetCoarseningInfoArray(CaseRequest) returns (CoarseningInfoArray) {}
18+
rpc GetTimeSteps(CaseRequest) returns (TimeStepDates) {}
19+
rpc GetSelectedCells(CaseRequest) returns (stream SelectedCells) {}
20+
rpc GetDaysSinceStart(CaseRequest) returns (DaysSinceStart) {}
21+
rpc GetCaseInfo(CaseRequest) returns (CaseInfo) {}
22+
rpc GetPdmObject(CaseRequest) returns (PdmObject) {}
23+
rpc GetReservoirBoundingBox(CaseRequest) returns (BoundingBox) {}
24+
}
25+
26+
message CaseRequest { int32 id = 1; }
27+
28+
message CaseInfo {
29+
int32 id = 1;
30+
int32 group_id = 2;
31+
string name = 3;
32+
string type = 4;
33+
}
34+
35+
message CaseInfoArray { repeated CaseInfo data = 1; }
36+
37+
message BoundingBox {
38+
double min_x = 1;
39+
double max_x = 2;
40+
double min_y = 3;
41+
double max_y = 4;
42+
double min_z = 5;
43+
double max_z = 6;
44+
}
45+
46+
message CaseGroup {
47+
int32 id = 1;
48+
string name = 2;
49+
}
50+
51+
message CaseGroups { repeated CaseGroup case_groups = 1; }
52+
53+
message GridCount { int32 count = 1; }
54+
55+
message CellCount {
56+
int32 active_cell_count = 1;
57+
int32 reservoir_cell_count = 2;
58+
}
59+
60+
enum PorosityModelType {
61+
MATRIX_MODEL = 0;
62+
FRACTURE_MODEL = 1;
63+
}
64+
65+
message CellInfoRequest {
66+
CaseRequest case_request = 1;
67+
PorosityModelType porosity_model = 2;
68+
}
69+
70+
message CellInfoArray { repeated CellInfo data = 1; }
71+
72+
message CellInfo {
73+
int32 grid_index = 1;
74+
int32 parent_grid_index = 2;
75+
int32 coarsening_box_index = 3;
76+
Vec3i local_ijk = 4;
77+
Vec3i parent_ijk = 5;
78+
}
79+
80+
message CoarseningInfoArray { repeated CoarseningInfo data = 1; }
81+
82+
message CoarseningInfo {
83+
Vec3i min = 1;
84+
Vec3i max = 2;
85+
}
86+
87+
message TimeStepDates { repeated TimeStepDate dates = 1; }
88+
89+
message TimeStepDate {
90+
int32 year = 1;
91+
int32 month = 2;
92+
int32 day = 3;
93+
int32 hour = 4;
94+
int32 minute = 5;
95+
int32 second = 6;
96+
}
97+
98+
message DaysSinceStart { repeated double day_decimals = 1; }
99+
100+
message SelectedCell {
101+
int32 grid_index = 1;
102+
Vec3i ijk = 2;
103+
}
104+
105+
message SelectedCells { repeated SelectedCell cells = 1; }

0 commit comments

Comments
 (0)