DATAGRAPH-1039 - Improve documentation.

Fix broken links.
Fix typos and add precisions on the contents of the conf properties file.

(cherry picked from commit 1389e6c)

README.adoc

@@ -110,7 +110,6 @@ Spring Data Neo4j will attempt to auto-configure itself using a file called `ogm
 
 [source,java]
 ----
-driver=org.neo4j.ogm.drivers.http.driver.HttpDriver
 URI=http://user:password@localhost:7474
 ----
 

src/main/asciidoc/migration.adoc

@@ -74,11 +74,11 @@ SDN provides automatic type conversion for the obvious candidates: byte[] and By
 BigInteger types. In order to define bespoke type conversions for particular entity attribute, you can annotate a
 field or method with `@Convert` to specify your own implementation of `org.neo4j.ogm.typeconversion.AttributeConverter`.
 
-You can find out more about type conversions here: <<reference_programming-model_conversion-custom,Custom Converters>>
+You can find out more about type conversions here: <<reference_programming-model_conversion,Custom Converters>>
 
 [[migration.4-0.date-format]]
 === Date Format Changes
-The default Date converter is <<reference_programming-model_conversion-built_in,@DateString>>.
+The default Date converter is <<reference:type-conversion:built-in,@DateString>>.
 
 SDN 3.x and earlier represented Dates as a String value consisting of the number of milliseconds since January 1, 1970, 00:00:00 GMT.
 
@@ -124,7 +124,7 @@ Some features of the previous annotations have been dropped.
 
 Overriding @Property Types::
 Support for overriding property types via arguments to @Property has been dropped. If your attribute requires
-a non-default conversion to and from a database property, you can use a <<custom_converters,Custom Converter>> instead.
+a non-default conversion to and from a database property, you can use a <<migration.4-0.custom_converters,Custom Converter>> instead.
 
 @Relationship enforceTargetType::
 In previous versions of Spring Data Neo4j, you would have to add an `enforceTargetType` attribute into every clashing

src/main/asciidoc/preface.adoc

@@ -17,7 +17,14 @@ It assumes the user is familiar with the Neo4j graph database as well as Spring
 [[preface.spring-data]]
 == Spring and Spring Data
 
-Spring Data uses Spring framework's http://docs.spring.io/spring/docs/5.0.x/spring-framework-reference/html/spring-core.html[core] functionality, such as the http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/beans.html[IoC] container, http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/validation.html#core-convert[type conversion system], http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/expressions.html[expression language], http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/jmx.html[JMX integration], and portable http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/dao.html#dao-exceptions[DAO exception hierarchy]. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use.
+Spring Data uses Spring framework's https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html[core] functionality,
+such as the https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#beans[IoC] container,
+https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#core-convert[type conversion system],
+https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#expressions[expression language],
+https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/integration.html#jmx[JMX integration],
+and portable https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/data-access.html#dao-exceptions[DAO exception hierarchy].
+While it is not important to know the Spring APIs, understanding the concepts behind them is.
+At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use.
 
 The core functionality of the Neo4J support can be used directly, with no need to invoke the IoC services of the Spring Container. This is much like Hibernate `Session` or JPA `EntityManager` which can be used 'standalone' without any other services of the Spring container. To leverage all the features of Spring Data Neo4j, such as the repository support, you will need to configure some parts of the library using Spring.
 

src/main/asciidoc/reference/getting-started.adoc

@@ -61,7 +61,8 @@ For more in depth configuration details please consult the Configuration section
 
 By default, SDN will use the BOLT driver to connect to Neo4j and you don't need to declare it as a separate dependency in your pom.
 If you want to use the embedded or HTTP drivers in your production application, you must add the following dependencies as well.
-(This dependency on the embedded driver is not required if you only want to use the embedded driver for testing. See the section on <<testing,Testing>> below for more information).
+(This dependency on the embedded driver is not required if you only want to use the embedded driver for testing.
+See the section on <<reference.getting_started.dependencies.testing,Testing>> below for more information).
 
 
 
@@ -172,7 +173,7 @@ public class MyConfiguration {
     @Bean
     public org.neo4j.ogm.config.Configuration configuration() {
         ConfigurationSource properties = new ClasspathConfigurationSource("ogm.properties");
-        org.neo4j.ogm.config.Configuration configuration = new org.neo4j.ogm.config.Configuration.Builder(properties)
+        org.neo4j.ogm.config.Configuration configuration = new org.neo4j.ogm.config.Configuration.Builder(properties).build();
         return configuration;
     }
 
@@ -236,9 +237,22 @@ Configuration can also be initialized from an external file like this.
 @Bean
 public org.neo4j.ogm.config.Configuration configuration() {
     ConfigurationSource properties = new ClasspathConfigurationSource("db.properties");
-    return new org.neo4j.ogm.config.Configuration.Builder(properties);
+    return new org.neo4j.ogm.config.Configuration.Builder(properties).build();
 }
 ----
+where `db.properties` looks like
+[source,properties]
+----
+URI=bolt://localhost
+username=user
+password=secret
+connection.pool.size=... #see java driver doc
+encryption.level=... #see java driver doc
+trust.strategy=... #see java driver doc
+trust.certificate.file=... #see java driver doc
+connection.liveness.check.timeout=... #see java driver doc
+verify.connection=... #see java driver doc
+----
 
 //TODO add configuration option with native driver
 

src/main/asciidoc/reference/neo4j-repositories.adoc

@@ -465,8 +465,8 @@ determines the actual one used.
 
 It is highly recommended that users understand how Spring Transactions work. Below are some excellent resources:
 
-* http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html/transaction.html[Spring Transaction Management]
-* http://graphaware.com/neo4j/2016/09/30/upgrading-to-sdn-42.html[Upgrading to Spring Data Neo4j 4.2]
+* https://docs.spring.io/spring/docs/current/spring-framework-reference/data-access.html#spring-data-tier[Spring Transaction Management]
+* https://graphaware.com/neo4j/2016/09/30/upgrading-to-sdn-42.html[Upgrading to Spring Data Neo4j 4.2]
 
 === Read only Transactions
 
@@ -591,8 +591,9 @@ Spring Data Neo4J allows developers to use JSR-303 annotations like `@NotNull` e
 While this is provided it's not a best practice. It is highly recommended to create JSR-303 annotations on actual Java Beans,
 similar to things like Data Transfer Objects (DTOs).
 
+[[reference_programming-model_conversion]]
 === Conversion Service
-It is possible to have Spring Data Neo4j use converters registered with http://docs.spring.io/spring/docs/current/spring-framework-reference/html/validation.html#core-convert[Spring's ConversionService].
+It is possible to have Spring Data Neo4j use converters registered with http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/validation.html#core-convert[Spring's ConversionService].
 In order to do this, provide `org.springframework.data.neo4j.conversion.MetaDataDrivenConversionService` as a Spring bean.
 
 .Provide MetaDataDrivenConversionService as a Spring bean

src/main/asciidoc/reference/projections.adoc

@@ -105,7 +105,7 @@ This projection has the following details:
 ====
 
 The backing domain model does not have these properties so we need to tell Spring Data from where they are obtained.
-Virtual properties are the place where `@Value` comes into play. The `cinemaName` getter is annotated with `@Value` to use http://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/html/expressions.html[SpEL expressions] pointing to the backing property `name`. You may have noticed `name` is prefixed with `target` which is the variable name pointing to the backing object. Using `@Value` on methods allows defining where and how the value is obtained.
+Virtual properties are the place where `@Value` comes into play. The `cinemaName` getter is annotated with `@Value` to use https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#expressions[SpEL expressions] pointing to the backing property `name`. You may have noticed `name` is prefixed with `target` which is the variable name pointing to the backing object. Using `@Value` on methods allows defining where and how the value is obtained.
 
 `@Value` gives full access to the target object and its nested properties. SpEL expressions are extremely powerful as the definition is always applied to the projection method.