Skip to content

Extracts test utilities and example generation code into a separate module #460

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Andy2003 merged 1 commit into from
Dec 22, 2025
Merged

Extracts test utilities and example generation code into a separate module #460

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 110 additions & 0 deletions doc-examples/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Copyright (c) "Neo4j"
~ Neo4j Sweden AB [http://neo4j.com]
~
~ This file is part of Neo4j Spatial.
~
~ Neo4j is free software: you can redistribute it and/or modify
~ it under the terms of the GNU General Public License as published by
~ the Free Software Foundation, either version 3 of the License, or
~ (at your option) any later version.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of
~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
~ GNU General Public License for more details.
~
~ You should have received a copy of the GNU General Public License
~ along with this program. If not, see <http://www.gnu.org/licenses/>.
-->

<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.neo4j</groupId>
<artifactId>neo4j-spatial</artifactId>
<version>2025.10.1-SNAPSHOT</version>
</parent>

<artifactId>neo4j-spatial-doc-examples</artifactId>

<dependencies>
<dependency>
<groupId>info.picocli</groupId>
<artifactId>picocli</artifactId>
<version>4.7.7</version>
</dependency>
<dependency>
<groupId>org.neo4j</groupId>
<artifactId>neo4j-spatial-test-utils</artifactId>
<version>2025.10.1-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.neo4j</groupId>
<artifactId>neo4j-spatial-cli-tools</artifactId>
<version>2025.10.1-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.neo4j</groupId>
<artifactId>neo4j-spatial-server-plugin</artifactId>
<version>2025.10.1-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.neo4j</groupId>
<artifactId>neo4j-kernel-test-utils</artifactId>
<version>${neo4j.version}</version>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.6.2</version>
<configuration>
<executable>java</executable>
<systemProperties>
<systemProperty>
<key>user.dir</key>
<value>${project.parent.basedir}</value>
</systemProperty>
</systemProperties>
</configuration>
<executions>
<execution>
<id>generate-api-docs</id>
<phase>compile</phase>
<goals><goal>exec</goal></goals>
<configuration>
<executable>java</executable>
<workingDirectory>${project.parent.basedir}</workingDirectory>
<arguments>
<argument>-classpath</argument>
<classpath/>
<argument>org.neo4j.spatial.doc.examples.ApiDocGenerator</argument>
</arguments>
</configuration>
</execution>
<execution>
<id>generate-examples</id>
<phase>compile</phase>
<goals><goal>exec</goal></goals>
<configuration>
<executable>java</executable>
<workingDirectory>${project.parent.basedir}</workingDirectory>
<arguments>
<argument>-classpath</argument>
<classpath/>
<argument>org.neo4j.spatial.doc.examples.ApiExampleGenerator</argument>
</arguments>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
108 changes: 67 additions & 41 deletions ...g/neo4j/gis/spatial/DocGeneratorTest.java → ...spatial/doc/examples/ApiDocGenerator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
package org.neo4j.gis.spatial;
package org.neo4j.spatial.doc.examples;

import static org.neo4j.configuration.GraphDatabaseSettings.DEFAULT_DATABASE_NAME;

import com.fasterxml.jackson.core.JsonProcessingException;
import java.io.BufferedWriter;
Expand All @@ -31,10 +33,9 @@
import java.util.Set;
import java.util.TreeMap;
import java.util.TreeSet;
import java.util.concurrent.Callable;
import java.util.stream.Stream;
import org.junit.jupiter.api.Test;
import org.neo4j.doc.domain.examples.Mapper;
import org.neo4j.exceptions.KernelException;
import org.neo4j.configuration.GraphDatabaseSettings;
import org.neo4j.gis.spatial.functions.SpatialFunctions;
import org.neo4j.gis.spatial.procedures.SpatialProcedures;
import org.neo4j.internal.kernel.api.procs.DescribedSignature;
Expand All @@ -45,41 +46,70 @@
import org.neo4j.kernel.api.procedure.GlobalProcedures;
import org.neo4j.kernel.api.procedure.ProcedureView;
import org.neo4j.kernel.internal.GraphDatabaseAPI;
import org.neo4j.spatial.doc.examples.utils.Mapper;
import org.neo4j.test.TestDatabaseManagementServiceBuilder;
import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;

public class DocGeneratorTest extends AbstractApiTest {
@Command(name = "ApiDocGenerator", mixinStandardHelpOptions = true)
public class ApiDocGenerator implements Callable<Integer> {

public static final String GENERATED_COMMENT = "// This file is generated by DocGeneratorTest, do not edit it manually\n";
@Option(names = {"-i", "--index-file"}, description = "The file location of the doc index")
private Path indexFile = Path.of("./docs/docs/modules/ROOT/partials/generated/api/index.adoc");

@Override
protected void registerApiProceduresAndFunctions() throws KernelException {
registerProceduresAndFunctions(SpatialFunctions.class);
registerProceduresAndFunctions(SpatialProcedures.class);
}
@Option(names = {"-n", "--nav-file"}, description = "The file location of the navigation")
private Path navFile = Path.of("./docs/docs/modules/ROOT/partials/generated/api-nav.adoc");

@Test
public void generateDocStub() throws IOException {
@Option(names = {"-p",
"--partials-root"}, description = "The root directory where the partials for the api doc should be placed in")
private Path partialsRoot = Path.of("./docs/docs/modules/ROOT/partials/generated/api");

GlobalProcedures procedures = ((GraphDatabaseAPI) db).getDependencyResolver()
.resolveDependency(GlobalProcedures.class);
ProcedureView currentView = procedures.getCurrentView();
@Option(names = {"-c",
"--customizable-root"}, description = "The root directory where the customizable doc file is placed in.")
private Path customizableRoot = Path.of("./docs/docs/modules/ROOT/pages/api");

Structure root = new Structure(null);
public static final String GENERATED_COMMENT =
"// This file is generated by " + ApiDocGenerator.class.getName() + ", do not edit it manually\n";

Stream.of(
currentView.getAllNonAggregatingFunctions(QueryLanguage.CYPHER_5),
currentView.getAllAggregatingFunctions(QueryLanguage.CYPHER_5),
currentView.getAllProcedures(QueryLanguage.CYPHER_5)
)
.flatMap(stream -> stream)
.forEach(root::add);
public static void main(String... args) {
int exitCode = new CommandLine(new ApiDocGenerator()).execute(args);
System.exit(exitCode);
}

Structure spatial = root.nested.get("spatial");
spatial.writeDoc();
spatial.writeNav();
spatial.writeSingleDocs();
@Override
public Integer call() throws Exception {
try (var neo4j = new TestDatabaseManagementServiceBuilder()
.setConfig(GraphDatabaseSettings.procedure_unrestricted, List.of("spatial.*"))
.impermanent()
.build()) {

GlobalProcedures procedures = ((GraphDatabaseAPI) neo4j.database(DEFAULT_DATABASE_NAME))
.getDependencyResolver()
.resolveDependency(GlobalProcedures.class);
procedures.registerProcedure(SpatialProcedures.class);
procedures.registerFunction(SpatialFunctions.class);

ProcedureView currentView = procedures.getCurrentView();
Structure root = new Structure(null);
Stream.of(
currentView.getAllNonAggregatingFunctions(QueryLanguage.CYPHER_5),
currentView.getAllAggregatingFunctions(QueryLanguage.CYPHER_5),
currentView.getAllProcedures(QueryLanguage.CYPHER_5)
)
.flatMap(stream -> stream)
.forEach(root::add);

Structure spatial = root.nested.get("spatial");
spatial.writeDoc();
spatial.writeNav();
spatial.writeSingleDocs();
}
System.out.println("API-Doc successfully generated!");
return 0;
}

private static class Structure {
private class Structure {

String namespace;
Map<String, Structure> nested = new TreeMap<>();
Expand All @@ -104,18 +134,16 @@ public void add(DescribedSignature sig) {
}

public void writeDoc() throws IOException {
Path file = Path.of("../docs/docs/modules/ROOT/partials/generated/api/index.adoc");
Files.createDirectories(file.getParent());
try (BufferedWriter writer = Files.newBufferedWriter(file)) {
Files.createDirectories(indexFile.getParent());
try (BufferedWriter writer = Files.newBufferedWriter(indexFile)) {
writer.append(GENERATED_COMMENT);
writer.append(generateIndex());
}
}

public void writeNav() throws IOException {
Path file = Path.of("../docs/docs/modules/ROOT/partials/generated/api-nav.adoc");
Files.createDirectories(file.getParent());
try (BufferedWriter writer = Files.newBufferedWriter(file)) {
Files.createDirectories(navFile.getParent());
try (BufferedWriter writer = Files.newBufferedWriter(navFile)) {
writer.append(GENERATED_COMMENT);
writer.append(this.generateNav());
}
Expand All @@ -133,13 +161,11 @@ public void writeSingleDocs() throws IOException {
private void writeSingleDoc(DescribedSignature entry) throws IOException {
String fqname = entry.name().toString();

Path customizedFile = Path.of("../docs/docs/modules/ROOT/pages/api", namespace, fqname + ".adoc");
Path customizedFile = customizableRoot.resolve( namespace).resolve( fqname + ".adoc");
if (!Files.exists(customizedFile)) {
Files.createDirectories(customizedFile.getParent());
String commented = Files.exists(
Path.of("../docs/docs/modules/ROOT/partials/generated/api", namespace,
fqname + "-examples.adoc"))
? "" : "// ";
String commented =
Files.exists(partialsRoot.resolve(namespace).resolve(fqname + "-examples.adoc")) ? "" : "// ";
Files.writeString(customizedFile,
"include::partial$generated/api/" + namespace + "/" + fqname + ".adoc[]\n\n"
+ commented + "== Examples\n"
Expand All @@ -148,7 +174,7 @@ private void writeSingleDoc(DescribedSignature entry) throws IOException {
+ "-examples.adoc[]\n");
}

Path file = Path.of("../docs/docs/modules/ROOT/partials/generated/api", namespace, fqname + ".adoc");
Path file = partialsRoot.resolve(namespace).resolve(fqname + ".adoc");
Files.createDirectories(file.getParent());

List<FieldSignature> inputs;
Expand Down
Loading