Skip to content

Commit

Permalink
Collect all Neo4j documentation into a single reference list
Browse files Browse the repository at this point in the history
  • Loading branch information
@jakewins @pontusmelke
jakewins authored and pontusmelke committed Apr 5, 2016
1 parent 3234e29 commit 36584a3
Show file tree
Hide file tree
Showing 34 changed files with 1,578 additions and 345 deletions.
25 changes: 0 additions & 25 deletions community/consistency-check/pom.xml
View file
Expand Up @@ -111,30 +111,5 @@ the relevant Commercial Agreement.
<type>test-jar</type> <type>test-jar</type>
<scope>test</scope> <scope>test</scope>
</dependency> </dependency>

</dependencies> </dependencies>

<build>
<plugins>
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<executions>
<execution>
<id>generate-source-based-documentation</id>
<phase>${generate-config-docs-phase}</phase>
<configuration>
<target>
<java classname="org.neo4j.kernel.configuration.docs.GenerateConfigDocumentation"
classpathref="maven.compile.classpath" failonerror="true">
<arg value="org.neo4j.consistency.ConsistencyCheckSettings" />
<arg value="${project.build.directory}/docs/ops/configuration-attributes.asciidoc" />
</java>
</target>
</configuration>
<goals><goal>run</goal></goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project> </project>
50 changes: 0 additions & 50 deletions community/dbms/pom.xml
View file
Expand Up @@ -70,54 +70,4 @@
<scope>test</scope> <scope>test</scope>
</dependency> </dependency>
</dependencies> </dependencies>

<build>
<plugins>
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.7</version>
<executions>
<execution>
<id>generate-source-based-config-documentation</id>
<phase>${generate-config-docs-phase}</phase>
<configuration>
<target>
<java classname="org.neo4j.kernel.configuration.docs.GenerateConfigDocumentation"
classpathref="maven.compile.classpath" failonerror="true">
<arg value="org.neo4j.dbms.DatabaseManagementSystemSettings"/>
<arg value="${project.build.directory}/docs/ops/configuration-attributes.asciidoc"/>
</java>
</target>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>ant-contrib</groupId>
<artifactId>ant-contrib</artifactId>
<version>1.0b3</version>
<exclusions>
<exclusion>
<groupId>ant</groupId>
<artifactId>ant</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant</artifactId>
<version>1.8.2</version>
</dependency>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant-apache-regexp</artifactId>
<version>1.8.2</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project> </project>
29 changes: 0 additions & 29 deletions community/kernel/pom.xml
View file
Expand Up @@ -119,35 +119,6 @@ the relevant Commercial Agreement.
</archive> </archive>
</configuration> </configuration>
</plugin> </plugin>
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<executions>
<execution>
<id>generate-source-based-documentation</id>
<phase>${generate-config-docs-phase}</phase>
<configuration>
<target>
<java classname="org.neo4j.kernel.configuration.docs.GenerateConfigDocumentation" classpathref="maven.test.classpath" failonerror="true">
<arg value="org.neo4j.graphdb.factory.GraphDatabaseSettings" />
<arg value="${project.build.directory}/docs/ops/configuration-attributes.asciidoc" />
</java>
<java classname="org.neo4j.kernel.configuration.docs.GenerateConfigDocumentation" classpathref="maven.test.classpath" failonerror="true">
<arg value="org.neo4j.graphdb.factory.GraphDatabaseSettings$BoltConnector" />
<arg value="${project.build.directory}/docs/ops/configuration-attributes-bolt-connector.asciidoc" />
</java>
</target>
</configuration>
<goals><goal>run</goal></goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant-launcher</artifactId>
<version>1.8.4</version>
</dependency>
</dependencies>
</plugin>
<plugin> <plugin>
<artifactId>maven-javadoc-plugin</artifactId> <artifactId>maven-javadoc-plugin</artifactId>
<configuration> <configuration>
Expand Down
6 changes: 6 additions & 0 deletions community/kernel/src/main/java/org/neo4j/graphdb/factory/GraphDatabaseSettings.java
View file
Expand Up @@ -494,6 +494,12 @@ public static class BoltConnector extends Connector
@Description( "Address the connector should bind to" ) @Description( "Address the connector should bind to" )
public final Setting<HostnamePort> address; public final Setting<HostnamePort> address;


// Used by config doc generator
public BoltConnector()
{
this("{bolt-connector-key}");
}

public BoltConnector(String key) public BoltConnector(String key)
{ {
super(key, ConnectorType.BOLT.name() ); super(key, ConnectorType.BOLT.name() );
Expand Down
15 changes: 15 additions & 0 deletions community/kernel/src/main/java/org/neo4j/helpers/Args.java
View file
Expand Up @@ -212,6 +212,11 @@ else if ( values.size() > 1 )
return values.get( 0 ).value(); return values.get( 0 ).value();
} }


/**
* Get a config option by name.
* @param key name of the option, without any `-` or `--` prefix, eg. "o".
* @return the string value of the option, or null if the user has not specified it
*/
public String get( String key ) public String get( String key )
{ {
return getSingleOptionOrNull( key ); return getSingleOptionOrNull( key );
Expand Down Expand Up @@ -320,11 +325,21 @@ public <T extends Enum<T>> T getEnum( Class<T> enumClass, String key, T defaultV
throw new IllegalArgumentException( "No enum instance '" + raw + "' in " + enumClass.getName() ); throw new IllegalArgumentException( "No enum instance '" + raw + "' in " + enumClass.getName() );
} }


/**
* Orphans are arguments specified without options flags, eg:
*
* <pre>myprogram -o blah orphan1 orphan2</pre>
*
* Would yield a list here of {@code "orphan1"} and {@code "orphan2"}.
*
* @return list of orphan arguments
*/
public List<String> orphans() public List<String> orphans()
{ {
return new ArrayList<>( this.orphans ); return new ArrayList<>( this.orphans );
} }


/** @see #orphans() **/
public String[] orphansAsArray() public String[] orphansAsArray()
{ {
return orphans.toArray( new String[orphans.size()] ); return orphans.toArray( new String[orphans.size()] );
Expand Down
41 changes: 25 additions & 16 deletions ...kernel/src/main/java/org/neo4j/kernel/configuration/docs/GenerateConfigDocumentation.java
View file
Expand Up @@ -20,42 +20,51 @@
package org.neo4j.kernel.configuration.docs; package org.neo4j.kernel.configuration.docs;


import java.io.File; import java.io.File;
import java.util.List;
import java.util.function.Function;


import org.neo4j.helpers.Args;
import org.neo4j.io.fs.FileUtils; import org.neo4j.io.fs.FileUtils;


/** /**
* Generates Asciidoc for the GraphDatabaseSettings class. * Generates Asciidoc for the GraphDatabaseSettings class.
*/ */
public class GenerateConfigDocumentation public class GenerateConfigDocumentation
{ {
public static void main( String[] args ) throws Exception public static void main( String[] argv ) throws Exception
{ {
File output = null; Args arguments = Args.parse( argv );
String bundleName = null;
if(args.length > 0) File output = arguments.has( "o" ) ? new File(arguments.get("o")) : null;
{ List<String> settingsClasses = arguments.orphans();
bundleName = args[0]; if(settingsClasses.size() == 0)

if(args.length > 1)
{
output = new File(args[1]).getAbsoluteFile();
}

} else
{ {
System.out.println("Usage: GenerateConfigDocumentation CONFIG_BUNDLE_CLASS [output file]"); System.out.println("Usage: GenerateConfigDocumentation [-o output file] SETTINGS_CLASS..");
System.exit(0); System.exit(0);
} }


String doc = new SettingsDocumenter().document( Class.forName( bundleName ) ); String doc = new SettingsDocumenter()
.document( settingsClasses.stream().map( classFromString ) );


if(output != null) if(output != null)
{ {
System.out.println("Saving docs for '"+bundleName+"' in '" + output.getAbsolutePath() + "'."); System.out.println("Saving docs in '" + output.getAbsolutePath() + "'.");
FileUtils.writeToFile(output, doc, false); FileUtils.writeToFile(output, doc, false);
} else } else
{ {
System.out.println(doc); System.out.println(doc);
} }
} }

private static Function<String,Class<?>> classFromString = (Function<String,Class<?>>) ( className ) -> {
try
{
return Class.forName( className );
}
catch ( ClassNotFoundException e )
{
throw new RuntimeException( e );
}
};

} }
32 changes: 8 additions & 24 deletions community/kernel/src/main/java/org/neo4j/kernel/configuration/docs/SettingDescription.java
View file
Expand Up @@ -38,29 +38,8 @@ public final class SettingDescription
private final boolean isMandatory; private final boolean isMandatory;
private final boolean hasDefault; private final boolean hasDefault;


public SettingDescription( String name, String description, String mandatoryDescription, String deprecationDescription, public SettingDescription( String id, String name, String description, String mandatoryDescription, String
String validationDescription, String defaultValue, deprecationDescription,
boolean isDeprecated, boolean isMandatory, boolean hasDefault )
{

this(
// {key} is used for documenting group config, and this is not
// allowed in asciidoc references. Strip out the curlies.
"config_" + (name.replace( "{", "").replace( "}", "" ) ),
// And similarly, curlies need to be escaped when used in prose text
name.replace( "{", "\\{" ).replace( "}", "\\}" ),

description, mandatoryDescription, deprecationDescription,
validationDescription, defaultValue, isDeprecated, isMandatory, hasDefault );
}

public SettingDescription( String id, String name, String description )
{
this( id, name, description, null, null, null, null, false, false, false );
}

private SettingDescription( String id, String name, String description,
String mandatoryDescription, String deprecationDescription,
String validationDescription, String defaultValue, String validationDescription, String defaultValue,
boolean isDeprecated, boolean isMandatory, boolean hasDefault ) boolean isDeprecated, boolean isMandatory, boolean hasDefault )
{ {
Expand All @@ -70,12 +49,17 @@ private SettingDescription( String id, String name, String description,
this.validationDescription = validationDescription; this.validationDescription = validationDescription;
this.defaultValue = defaultValue; this.defaultValue = defaultValue;
this.isDeprecated = isDeprecated; this.isDeprecated = isDeprecated;
this.name = name; this.name = name.replace( "{", "\\{" ).replace( "}", "\\}" );
this.description = description; this.description = description;
this.isMandatory = isMandatory; this.isMandatory = isMandatory;
this.hasDefault = hasDefault; this.hasDefault = hasDefault;
} }


public SettingDescription( String id, String name, String description )
{
this( id, name, description, null, null, null, null, false, false, false );
}

public String id() public String id()
{ {
return id; return id;
Expand Down
44 changes: 38 additions & 6 deletions community/kernel/src/main/java/org/neo4j/kernel/configuration/docs/SettingsDescription.java
View file
Expand Up @@ -20,10 +20,10 @@
package org.neo4j.kernel.configuration.docs; package org.neo4j.kernel.configuration.docs;


import java.lang.reflect.Field; import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.LinkedList; import java.util.LinkedList;
import java.util.List; import java.util.List;
import java.util.Optional; import java.util.Optional;
import java.util.function.Function;
import java.util.stream.Stream; import java.util.stream.Stream;


import org.neo4j.graphdb.config.Setting; import org.neo4j.graphdb.config.Setting;
Expand All @@ -40,20 +40,19 @@ public class SettingsDescription
/** /**
* Create a description of a given class. * Create a description of a given class.
*/ */
public static SettingsDescription describe( Class<?> settingClass ) throws Exception public static SettingsDescription describe( Class<?> settingClass )
{ {
String classDescription = settingClass.isAnnotationPresent( Description.class ) String classDescription = settingClass.isAnnotationPresent( Description.class )
? settingClass.getAnnotation( Description.class ).value() ? settingClass.getAnnotation( Description.class ).value()
: "List of configuration settings"; : "List of configuration settings";
String settingsName = settingClass.getName().replace( "$", "-" );
Object instance = null; Object instance = null;


for(Class<?> cls = settingClass; cls != null; cls = cls.getSuperclass() ) for(Class<?> cls = settingClass; cls != null; cls = cls.getSuperclass() )
{ {
if( cls.isAnnotationPresent( Group.class ) ) if( cls.isAnnotationPresent( Group.class ) )
{ {
// Group classes are special, we need to instantiate them to read their instance = groupInstance( settingClass );
// configuration, this is how the group config DSL works
instance = settingClass.getConstructor( String.class ).newInstance( "{key}" );
break; break;
} }
} }
Expand Down Expand Up @@ -87,6 +86,7 @@ public static SettingsDescription describe( Class<?> settingClass ) throws Excep
} }


settings.add( new SettingDescription( settings.add( new SettingDescription(
"config_" + (name.replace( "{", "").replace( "}", "" ) ),
name, description, name, description,
mandatoryMessage, mandatoryMessage,
deprecationMessage, deprecationMessage,
Expand All @@ -101,11 +101,25 @@ public static SettingsDescription describe( Class<?> settingClass ) throws Excep


return new SettingsDescription( return new SettingsDescription(
// Nested classes have `$` in the name, which is an asciidoc keyword // Nested classes have `$` in the name, which is an asciidoc keyword
settingClass.getName().replace( "$", "-" ), settingsName,
classDescription, classDescription,
settings ); settings );
} }


private static Object groupInstance( Class<?> settingClass )
{
try
{
// Group classes are special, we need to instantiate them to read their
// configuration, this is how the group config DSL works
return settingClass.newInstance();
}
catch(Exception e)
{
throw new RuntimeException( e );
}
}

private static Optional<Setting<?>> fieldAsSetting( Class<?> settingClass, Object instance, Field field ) private static Optional<Setting<?>> fieldAsSetting( Class<?> settingClass, Object instance, Field field )
{ {
Setting<?> setting; Setting<?> setting;
Expand Down Expand Up @@ -162,4 +176,22 @@ public String name()
{ {
return name; return name;
} }

/**
* Combine this description with another one. This is an immutable operation,
* meaning it returns a new description that is the combination of this and the
* one passed in.
*
* The name and description is taken from this description, name and setting
* from the provided one are discarded.
*
* @param other another setting description
* @return the union of this and the provided settings description
*/
public SettingsDescription union( SettingsDescription other )
{
ArrayList<SettingDescription> union = new ArrayList<>( this.settings );
union.addAll( other.settings );
return new SettingsDescription( name, description, union );
}
} }

0 comments on commit 36584a3

Please sign in to comment.