lokidundun opened a new pull request, #492: URL: https://github.com/apache/hugegraph-doc/pull/492
## Purpose of the PR Refs #491 — addresses the Computer / Vermeer items, both AI items, and both HugeGraph items in Chinese and English. The Toolchain item and the Release 1.8.0 gate remain open. Readers currently encounter outdated REST paths and Vermeer ports, an example that reads a graph before its load task finishes, missing navigation links, and undocumented Server startup-timeout controls. This PR corrects those examples and fills the documentation gaps across 12 pages. ## Before → after | Before | After | | --- | --- | | Computer result-query examples use `/graphs/hugegraph/...`. | Both languages use `/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode` and `/graphspaces/DEFAULT/graphs/hugegraph/graph/vertices`. | | Vermeer REST and Python examples use `8688`, without a matching Docker port mapping. | Examples consistently use master HTTP port `6688`, explicitly publish `6688:6688`, distinguish master gRPC port `6689`, and include a host-side HTTP check. | | The AI follow-up lists omit the Vermeer Python Client guide. | Both lists link to the guide beside the existing Python client link. | | Server configuration indexes omit the existing backend guides. | Both indexes link to HBase, HStore, and RocksDB under a backend configuration section. | | The Docker guide does not explain the Server startup wait or how to extend it. | Both languages document `HG_SERVER_STARTUP_TIMEOUT_S`, its 120-second default, 1–86400 range, failure behavior, a 300-second Compose override, and its independence from health-check timing. | | The SDK example reads task status once and immediately reads the graph. | It polls the created task with a deadline, reads the graph only after `loaded`, and raises clear errors for failed/canceled tasks, API errors, and polling timeout. | ## Main changes - Update the two Computer REST paths in both quick-start pages. - Align Vermeer startup guidance, REST examples, and Python client connections on HTTP port `6688`; publish the port in Compose and `docker run`, and add `curl --fail --show-error http://localhost:6688/graphs`. Replace non-breaking spaces in the English Compose indentation with normal spaces so the YAML can be copied. - Add the Vermeer SDK follow-up link and the three Server backend configuration links in both languages. - Document Server startup-timeout validation and failure behavior, with an override example and an explanation of the separate Docker health-check budget. - Add bounded polling to the SDK load example, including explicit HTTP timeouts, API error checks, and handling for `loaded`, `error`, and `canceled`. Keep the Chinese and English executable examples identical. Explain that client timeout does not cancel the server task. ## Screenshots The comparisons below render actual Markdown excerpts from `f001c1d` (before) and `de7eb37` (after). They show documentation content changes, not a full Hugo build or live service execution. Chinese equivalents are included in the screenshot package. ### Computer: graph-space REST paths <img width="1600" height="804" alt="image" src="https://github.com/user-attachments/assets/2ee9b552-79ec-4155-a092-f0bf08ff6aa3"; /> ### Vermeer: HTTP port, Docker publishing and Python client <img width="1600" height="1182" alt="image" src="https://github.com/user-attachments/assets/8bf0b956-dd78-40a9-90f0-0e8c15a90430"; /> ### AI quick start: Vermeer SDK navigation <img width="1600" height="670" alt="image" src="https://github.com/user-attachments/assets/55fef9ed-4b71-4beb-815d-727013b3506b"; /> ### Server configuration: backend navigation <img width="1600" height="744" alt="image" src="https://github.com/user-attachments/assets/c2fa3a22-09d9-4208-9e74-63cb21c890a5"; /> ### Docker guide: Server startup timeout <img width="1600" height="1175" alt="image" src="https://github.com/user-attachments/assets/1bb9c066-e1a3-44a6-8c9e-de07682bd033"; /> ### Vermeer SDK: wait for the load task before reading the graph <img width="1600" height="1299" alt="image" src="https://github.com/user-attachments/assets/ee53acc4-9b92-403c-8eb2-7768e80306a9"; /> ## Validation - Ran 15 offline checks against the extracted documentation examples using the real local SDK with simulated API responses and time: delayed success, immediate success, task failure, cancellation, timeout, task creation failure, task lookup failure, and bilingual executable-code parity. All passed. The original delayed-load examples failed because they read the graph while the task was still `waiting`. - Checked all eight newly added navigation targets in the Chinese and English content trees. - Checked the startup-timeout default, accepted range, validation, startup invocation, and Compose environment forwarding against the Server source referenced by the issue (`60c8803d5a85943eaa05e74eb37fe7d57b2256a0`). - Checked load-task terminal states against the Vermeer source (`04985bbc9907c7b6c9a8fe8833323df049f9bd9b`). - `git -c core.whitespace=cr-at-eol diff --check f001c1d..de7eb37` passes. The setting accounts for the existing CRLF line endings in the Vermeer pages. - No project build was run for this revision. The revised SDK polling example and Server startup-timeout override have not been exercised against live services; the screenshots do not constitute runtime validation. ## TODO - [ ] **Toolchain: Kafka `skipped_line` behavior.** Decide whether Kafka records should support regex filtering. Either implement filtering before parsing, or remove the unsupported option and examples from both language pages. Align the default-behavior description and add focused coverage for matching and non-matching records. - [ ] **Release 1.8.0 gate: pending PR documentation audit.** Inventory candidate unmerged PRs across HugeGraph, Toolchain, AI, and Computer / Vermeer; review user-visible changes; record each PR's Chinese/English documentation impact or no-docs-needed disposition; complete required updates and validation; refresh the inventory before the release branch or tag is cut. These two items are outside this PR. Keep #491 open; this PR does not claim the release documentation gate is satisfied. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
