This is an automated email from the ASF dual-hosted git repository.
Cole-Greer pushed a commit to branch docs-3.7
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/docs-3.7 by this push:
new 6d064e374f cleanup
6d064e374f is described below
commit 6d064e374f16e298d9af08aa1d8e420d7095d05a
Author: Cole Greer <[email protected]>
AuthorDate: Tue Jun 9 10:10:21 2026 -0700
cleanup
---
CHANGELOG.asciidoc | 5 -
.../dev/developer/development-environment.asciidoc | 26 +--
tools/tinkerpop-docs/REQUIREMENTS.md | 243 ---------------------
tools/tinkerpop-docs/pom.xml | 10 -
.../src/main/resources/hadoop-conf/README | 34 ---
5 files changed, 7 insertions(+), 311 deletions(-)
diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
index 9eda62efb4..f710d91f02 100644
--- a/CHANGELOG.asciidoc
+++ b/CHANGELOG.asciidoc
@@ -25,11 +25,6 @@
image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
[[release-3-7-7]]
=== TinkerPop 3.7.7 (Release Date: NOT OFFICIALLY RELEASED YET)
-* Restart the documentation build's Gremlin Console with conflicting plugins
excluded per-book (via the `gremlin-docs-plugins-exclude` attribute), so Neo4j
(Scala 2.11) and Spark (Scala 2.12) no longer collide on a shared classpath.
-* Updated the developer documentation to describe the Maven/AsciidoctorJ
documentation build and removed references to the retired shell/AWK
preprocessor.
-* Apply syntax highlighting to standalone and manual language-variant tab
blocks in the documentation build, matching the highlighting already applied to
`gremlin-groovy` tabs.
-* Scope the Hadoop-Gremlin documentation `hdfs.ls()` examples to the copied
graph file so the rendered docs no longer list the build machine's local home
directory.
-
* Fixed conjoin has incorrect null handling.
* Expanded `gremlin-python` CI matrix to test against Python 3.9, 3.10, 3.11,
3.12, and 3.13.
* Add Node 26 support for `gremlin-javascript` and `gremlint`.
diff --git a/docs/src/dev/developer/development-environment.asciidoc
b/docs/src/dev/developer/development-environment.asciidoc
index 4fd92f9be1..9ff47464cd 100644
--- a/docs/src/dev/developer/development-environment.asciidoc
+++ b/docs/src/dev/developer/development-environment.asciidoc
@@ -122,29 +122,17 @@ an issue when working with SNAPSHOT dependencies.
[[documentation-environment]]
=== Documentation Environment
-The documentation generation process is Maven-based: an
link:https://asciidoctor.org/[AsciidoctorJ] extension
-(`tools/tinkerpop-docs`) walks each AsciiDoc book, executes the
`[gremlin-groovy]` code blocks against a long-lived
+The core of the documentation generation process is an
link:https://asciidoctor.org/[AsciidoctorJ] extension
+(`tools/tinkerpop-docs`) which walks each AsciiDoc book, executes the
`[gremlin-groovy]` code blocks against a long-lived
Gremlin Console subprocess, and renders the console output as tabbed HTML. The
orchestration script
-`bin/process-docs.sh` wraps this: it validates the Gremlin Console and Gremlin
Server distributions, installs the
-required plugins into the console, starts a Gremlin Server (for the `:remote`
examples) and a Gephi mock, then invokes
-Maven to run the extension. Javadocs should be built using Java 11.
+`bin/process-docs.sh` wraps this and acts as the entrypoint: it validates the
Gremlin Console and Gremlin Server
+distributions, installs the required plugins into the console, starts a
Gremlin Server (for the `:remote` examples) and
+a Gephi mock, then invokes Maven to run the extension. Javadocs should be
built using Java 11.
-NOTE: A previous implementation of this process was not Maven-based and
instead relied on a pipeline of shell and AWK
-scripts under `docs/preprocessor` and `docs/postprocessor`. Those scripts have
been removed; the console session scope
-also changed from per-file to per-book as a result (see
<<docs-plugin-exclusions>>).
-
-The build runs Spark/Hadoop OLAP examples against the local filesystem
(`fs.defaultFS=file:///`), so a running Hadoop
-cluster is *not* required for an ordinary documentation build. The one
exception is the
-link:https://tinkerpop.apache.org/docs/x.y.z/recipes/#olap-spark-yarn[Spark-on-YARN
recipe], whose example targets a
-real YARN cluster and is therefore rendered from pre-captured output rather
than executed live. `bin/process-docs.sh`
-sets `HADOOP_GREMLIN_LIBS` for the console automatically. The YARN recipe text
also references the `zip` program, so
-install it if you do not already have it.
-
-Before generating documentation, build the Gremlin Console and Gremlin Server
distributions that the process consumes
-(include the Neo4j artifacts so the Neo4j examples can run):
+Before generating documentation, build the build all of the dependencies that
the process consumes:
[source,text]
-mvn clean install -pl :gremlin-console,:gremlin-server -am -DskipTests
-DincludeNeo4j
+mvn clean install -pl
:gremlin-console,:gremlin-server:spark-gremlin,:neo4j-gremlin -am -DskipTests
-DincludeNeo4j
Documentation can then be generated locally with:
diff --git a/tools/tinkerpop-docs/REQUIREMENTS.md
b/tools/tinkerpop-docs/REQUIREMENTS.md
deleted file mode 100644
index 2df1d336c2..0000000000
--- a/tools/tinkerpop-docs/REQUIREMENTS.md
+++ /dev/null
@@ -1,243 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# TinkerPop Documentation Build - Requirements
-
-## Overview
-
-The documentation build system generates TinkerPop's reference documentation
from AsciiDoc sources. It processes `[gremlin-groovy]` code blocks by executing
them against a real Gremlin Console and producing tabbed output with console
results and manual language variant tabs.
-
-## Architecture
-
-### Components
-
-1. **`tinkerpop-docs`** - An AsciidoctorJ extension (standalone Maven module
under `tools/`) that processes gremlin code blocks during AsciiDoc rendering.
-2. **`bin/process-docs.sh`** - Shell script that orchestrates the full build:
installs plugins, starts required services, and invokes Maven/Asciidoctor.
-3. **Gremlin Console** - A long-running console subprocess used for code
execution (one per document/book).
-4. **Gremlin Server** - Started for remote connection examples.
-5. **Gephi Mock** - A mock HTTP server (`bin/gephi-mock.py`) for Gephi plugin
examples.
-
-### Module Location
-
-The `tinkerpop-docs` module lives at `tools/tinkerpop-docs/`. It uses the root
`tinkerpop` pom as its Maven parent (for version inheritance) but is NOT part
of the main reactor. It must be built separately before running the docs build.
-
-### Extension Type
-
-- **Treeprocessor**: Walks the AST after parsing, finds `[gremlin-groovy]`
listing blocks by style attribute, replaces them with tabbed HTML pass blocks.
-- **Postprocessor**: Applies callout fixes, removes empty comment spans,
replaces `x.y.z` version placeholder in rendered HTML.
-- Registered via SPI
(`META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry`).
-- Targets **AsciidoctorJ 2.5.x** for compatibility with existing
asciidoctor-maven-plugin 2.2.4.
-
-## Functional Requirements
-
-### FR-1: Gremlin Code Block Processing
-
-The extension SHALL walk the AsciiDoc AST and transform listing blocks with
style `gremlin-groovy` into tabbed HTML output containing:
-
-- A "console (<lang>)" tab showing the Gremlin prompt, input, and execution
output (syntax highlighted as Groovy via coderay)
-
-### FR-2: Console Execution
-
-- The extension SHALL execute code blocks against a real Gremlin Console
process to produce authentic console output.
-- The console process SHALL be started once per document (book-scoped) and
reused across all blocks, maintaining session state.
-- The console SHALL have TinkerGraph, SPARQL, Hadoop, and Spark plugins
activated.
-
-**Note:** The old system used per-file console sessions. The new book-scoped
approach is safe because every non-`existing` block reinitializes its graph.
This scope change should be noted in commit messages and PR descriptions.
-
-### FR-3: Graph Initialization
-
-For each block, the extension SHALL inject initialization code before
executing the block's content:
-
-- `[gremlin-groovy,<graph>]`: `graph = TinkerFactory.create<Graph>(); g =
graph.traversal()`
-- `[gremlin-groovy]` (no graph): `graph = TinkerGraph.open(); g =
graph.traversal()`
-- `[gremlin-groovy,existing]`: No initialization (reuses current state)
-
-Initialization also includes:
-- Cleanup: delete `/tmp/neo4j` and `/tmp/tinkergraph.kryo` if they exist
-- `:set max-iteration 100`
-- Graph initialization SHALL be skipped when consecutive blocks use the same
graph (NFR-4)
-
-Supported graph names: `modern`, `classic`, `theCrew`, `kitchenSink`,
`gratefulDead`
-
-### FR-4: Error Handling in Code Blocks
-
-- When a Gremlin statement produces a runtime error (signalled by the console's
- `Display stack trace? [yN]` prompt), the extension SHALL fail the docs
build, reporting the
- failing statement. Executed `gremlin-groovy` blocks are not expected to
error; documentation
- examples that intentionally show errors are authored as manual
`[source,text]`/`[source,<lang>]`
- blocks (Gremlin error output goes to the console's stderr and is not
captured into rendered
- output by design).
-- The "Display stack trace? [yN]" prompt SHALL be answered automatically
(without user
- intervention) solely to unblock the console process and detect the error;
the build then fails.
-- A statement exceeding the execution timeout, or a console that dies and does
not recover after
- a single restart-and-retry, SHALL fail the build. The timeout is a failsafe
against indefinite
- hanging, not an expected path.
-
-### FR-5: Manual Language Variant Tabs
-
-- When `[source,<lang>]` blocks immediately follow a `[gremlin-groovy]` block
(as consecutive AST siblings), they SHALL be consumed and rendered as
additional tabs alongside the console output.
-- Supported languages: `groovy`, `java`, `csharp`, `javascript`, `python`, `go`
-- Consumption stops at the first non-matching sibling block.
-
-### FR-7: Standalone Tab Groups
-
-- `[source,<lang>,tab]` blocks SHALL be grouped into tabbed UI independently
of gremlin blocks.
-- Consecutive `[source,<lang>]` blocks following a `[source,<lang>,tab]` block
are grouped together.
-
-### FR-8: Dry-Run Mode
-
-- When `gremlin-docs-dryrun` attribute is set, the extension SHALL skip
console execution.
-- Code blocks SHALL be formatted with `gremlin>` prompts but no execution
output.
-- Tab structure (manual tabs, standalone tab groups) SHALL still render fully.
-- Dry-run mode SHALL NOT require a built Gremlin Console or Server.
-
-## Out of Scope (Initial Release)
-
-### FR-6: Auto-Translation (DEFERRED)
-
-Auto-translation of Gremlin to language variants via GremlinTranslator is not
included in the initial scope. Only manual language variant tabs (FR-5) are
supported.
-
-### FR-9: Rouge Syntax Highlighting (DEFERRED)
-
-Existing coderay highlighting is retained. Rouge would fix C# highlighting but
this is a pre-existing issue.
-
-## Non-Functional Requirements
-
-### NFR-1: Fail-Fast on Missing Dependencies
-
-- If the `gremlin-docs-console-home` attribute is not set and the build is NOT
in dry-run mode, the extension SHALL throw an error immediately with a clear
message indicating the Console must be built.
-
-### NFR-2: Timeout Safety Net
-
-- Console communication SHALL have a 30-second timeout to prevent infinite
hangs from unexpected console states.
-- A timeout SHALL fail the build with a clear error message including the
buffer contents at the time of timeout.
-
-### NFR-3: Progress Visibility
-
-- The extension SHALL log (at INFO level) each gremlin block being processed,
including the first line of code.
-- The extension SHALL log each statement being executed.
-- Console stderr output SHALL be logged at INFO level for diagnostic
visibility.
-
-### NFR-4: Build Performance
-
-- The Console communication protocol SHALL NOT introduce artificial delays (no
polling timeouts for expected responses).
-- Graph initialization SHALL be skipped when consecutive blocks use the same
graph.
-
-## Console Communication Protocol
-
-### Prompt-Based Boundary Detection
-
-The extension communicates with the Gremlin Console using prompt-based
boundary detection:
-
-1. The console outputs `gremlin>` (without trailing newline) after each
statement completes.
-2. The extension reads character-by-character and detects when the buffer ends
with `gremlin>`.
-3. Continuation prompts (`......N>`) are skipped — only `gremlin>` signals
statement completion.
-
-### Error Prompt Handling
-
-When a statement errors, the console writes "Display stack trace? [yN]" to
stderr and blocks reading from stdin:
-
-1. A stderr-draining thread detects "Display stack trace?" and sets a flag.
-2. The main thread's read loop checks this flag while waiting for stdout data.
-3. When the flag is set, a blank line is sent to stdin to dismiss the prompt.
-4. The console then prints `gremlin>` to stdout, unblocking the read.
-
-### Pre-Statement Dismissal
-
-Before each statement, any pending error prompt from a previous call is
dismissed:
-
-1. Check the `errorPromptPending` flag.
-2. If set, send a blank line and wait for the resulting `gremlin>` prompt.
-
-## Tabbed HTML Output
-
-### Structure
-
-Tab HTML uses CSS-only radio button tabs matching existing `tinkerpop.css`
styles:
-- `<section class="tabs tabs-N">` container
-- Radio inputs + labels for tab switching
-- `<div class="tabcontent">` panels
-- Tab IDs use a deterministic sequential counter (no timestamps)
-
-### Console Tab
-
-- Labeled "console (<lang>)" (e.g., "console (groovy)")
-- Content wrapped as `[source,groovy]` for coderay syntax highlighting
-- Callout markers rendered as `// <N>` comments
-
-### Plugin Conflict Management
-
-Plugin conflicts between chapters are managed via AsciiDoc document attributes:
-
-```asciidoc
-// Exclude spark-gremlin to avoid Spark jar conflicts with Neo4j's Spark
dependencies
-:gremlin-docs-plugins-exclude: spark-gremlin
-```
-
-When the extension encounters this attribute, it shuts down the current
console, toggles plugin directories, and starts a new console. Each usage must
include an inline comment explaining the conflict.
-
-## Build Invocation
-
-### Full Build (with execution)
-
-```
-mvn clean install -pl :gremlin-server,:gremlin-console -am -DskipTests
-bin/process-docs.sh
-```
-
-### Dry-Run (layout only, no Console needed)
-
-```
-bin/process-docs.sh --dry-run
-```
-
-### Output
-
-Final HTML documentation is placed in `target/docs/htmlsingle/`.
-
-## Dependencies
-
-| Dependency | Purpose |
-|---|---|
-| Gremlin Console distribution | Code execution |
-| Gremlin Server distribution | Remote connection examples |
-| `sparql-gremlin` plugin | SPARQL examples |
-| `hadoop-gremlin` plugin | Hadoop examples (local filesystem mode) |
-| `spark-gremlin` plugin | Spark examples (local mode) |
-| `gephi-mock.py` | Gephi plugin examples |
-
-### Hadoop Configuration
-
-The docs build does NOT require an external Hadoop cluster. A docs-specific
`core-site.xml` configures `fs.defaultFS=file:///` so the `hdfs` binding
operates on the local filesystem. `spark.master=local[4]` and
`jarsInDistributedCache=false` ensure Spark runs in-process.
-
-## Configuration
-
-The extension is configured via Asciidoctor document attributes:
-
-| Attribute | Description |
-|---|---|
-| `gremlin-docs-console-home` | Path to the unpacked Gremlin Console
distribution |
-| `gremlin-docs-hadoop-libs` | Path to Hadoop library jars for
HADOOP_GREMLIN_LIBS |
-| `gremlin-docs-dryrun` | When present, enables dry-run mode |
-| `gremlin-docs-plugins-exclude` | Comma-separated list of plugins to exclude
(triggers console restart) |
-
-These attributes are passed via the Maven command line (resolved by
`bin/process-docs.sh`):
-```
--Dasciidoctor.attributes="gremlin-docs-console-home=/path/to/console
gremlin-docs-hadoop-libs=/path/to/libs"
-```
diff --git a/tools/tinkerpop-docs/pom.xml b/tools/tinkerpop-docs/pom.xml
index b7d3c4db16..a327ca4089 100644
--- a/tools/tinkerpop-docs/pom.xml
+++ b/tools/tinkerpop-docs/pom.xml
@@ -66,16 +66,6 @@ limitations under the License.
<release>11</release>
</configuration>
</plugin>
- <plugin>
- <groupId>org.apache.rat</groupId>
- <artifactId>apache-rat-plugin</artifactId>
- <configuration>
- <excludes>
- <exclude>REQUIREMENTS.md</exclude>
-
<exclude>src/main/resources/META-INF/services/**</exclude>
- </excludes>
- </configuration>
- </plugin>
</plugins>
</build>
</project>
diff --git a/tools/tinkerpop-docs/src/main/resources/hadoop-conf/README
b/tools/tinkerpop-docs/src/main/resources/hadoop-conf/README
deleted file mode 100644
index 969c3a5a44..0000000000
--- a/tools/tinkerpop-docs/src/main/resources/hadoop-conf/README
+++ /dev/null
@@ -1,34 +0,0 @@
-Hadoop Configuration for Docs Builds
-=====================================
-
-This directory contains Hadoop configuration files used during TinkerPop
-documentation builds. These files allow SparkGraphComputer and Hadoop
-filesystem operations (copyFromLocal, ls, head) to work against the local
-filesystem without requiring any Hadoop daemons.
-
-Files
------
-
-core-site.xml
- Sets fs.defaultFS=file:/// so all HDFS API calls resolve to the local
- filesystem. No NameNode or DataNode is needed.
-
-hadoop-docs.properties
- Sets gremlin.hadoop.jarsInDistributedCache=false since all jars are
- already on the local classpath. No ResourceManager or NodeManager is
- needed.
-
-Usage
------
-
-The docs build orchestration script (phase 8) adds this directory to the
-Gremlin Console classpath so that Hadoop picks up core-site.xml
-automatically. The properties file can be loaded explicitly in console
-scripts or referenced as a graph configuration source.
-
-Prerequisites
--------------
-
-- Java (version matching the project build)
-- spark.master=local[4] (configured elsewhere in the docs build)
-- NO Hadoop daemons required (NameNode, DataNode, ResourceManager, NodeManager)
