Polishing.

Refine navigation structure.

See #3080

Author: mp911de

.gitignore

@@ -11,4 +11,5 @@ target/
 node_modules
 package-lock.json
 package.json
-node
+node
+build/

README.adoc

@@ -1,6 +1,3 @@
-image:https://spring.io/badges/spring-data-jpa/ga.svg[Spring Data JPA,link=https://projects.spring.io/spring-data-jpa/#quick-start]
-image:https://spring.io/badges/spring-data-jpa/snapshot.svg[Spring Data JPA,link=https://projects.spring.io/spring-data-jpa/#quick-start]
-
 = Spring Data JPA image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-jpa%2Fmain&subject=Build[link=https://jenkins.spring.io/view/SpringData/job/spring-data-jpa/] https://gitter.im/spring-projects/spring-data[image:https://badges.gitter.im/spring-projects/spring-data.svg[Gitter]]
 
 Spring Data JPA, part of the larger https://projects.spring.io/spring-data[Spring Data] family, makes it easy to implement JPA-based repositories.
@@ -104,7 +101,7 @@ Add the Maven dependency:
 <dependency>
   <groupId>org.springframework.data</groupId>
   <artifactId>spring-data-jpa</artifactId>
-  <version>${version}.RELEASE</version>
+  <version>${version}</version>
 </dependency>
 ----
 
@@ -115,7 +112,7 @@ If you'd rather like the latest snapshots of the upcoming major version, use our
 <dependency>
   <groupId>org.springframework.data</groupId>
   <artifactId>spring-data-jpa</artifactId>
-  <version>${version}.BUILD-SNAPSHOT</version>
+  <version>${version}-SNAPSHOT</version>
 </dependency>
 
 <repository>
@@ -130,7 +127,7 @@ If you'd rather like the latest snapshots of the upcoming major version, use our
 Having trouble with Spring Data? We’d love to help!
 
 * Check the
-https://docs.spring.io/spring-data/jpa/docs/current/reference/html/[reference documentation], and https://docs.spring.io/spring-data/jpa/docs/current/api/[Javadocs].
+https://docs.spring.io/spring-data/jpa/reference/[reference documentation], and https://docs.spring.io/spring-data/jpa/docs/current/api/[Javadocs].
 * Learn the Spring basics – Spring Data builds on Spring Framework, check the https://spring.io[spring.io] web-site for a wealth of reference documentation.
 If you are just starting out with Spring, try one of the https://spring.io/guides[guides].
 * If you are upgrading, check out the https://github.com/spring-projects/spring-data-jpa/releases[Spring Data JPA release notes] and scroll down to the one you're considering. See the details there. (Also check out the https://github.com/spring-projects/spring-data-jpa/releases/latest[latest stable release])
@@ -159,7 +156,7 @@ You also need JDK 17 or above.
  $ ./mvnw clean install
 ----
 
-If you want to build with the regular `mvn` command, you will need https://maven.apache.org/run-maven/index.html[Maven v3.5.0 or above].
+If you want to build with the regular `mvn` command, you will need https://maven.apache.org/run-maven/index.html[Maven v3.8.0 or above].
 
 _Also see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] if you wish to submit pull requests, and in particular please sign the https://cla.pivotal.io/sign/spring[Contributor’s Agreement] before your first non-trivial change._
 
@@ -169,10 +166,10 @@ Building the documentation builds also the project without running tests.
 
 [source,bash]
 ----
- $ ./mvnw clean install -Pdistribute
+ $ ./mvnw clean install -Pantora
 ----
 
-The generated documentation is available from `target/site/reference/html/index.html`.
+The generated documentation is available from `target/antora/site/index.html`.
 
 == Guides
 

src/main/antora/antora-playbook.yml

@@ -8,7 +8,7 @@ antora:
       root_component_name: 'data-jpa'
 site:
   title: Spring Data JPA
-  url: https://docs.spring.io/spring-data-jpa/reference/
+  url: https://docs.spring.io/spring-data/jpa/reference/
 content:
   sources:
     - url: ./../../..

src/main/antora/modules/ROOT/nav.adoc

@@ -1,34 +1,35 @@
 * xref:index.adoc[Overview]
 ** xref:commons/upgrade.adoc[]
-* xref:repositories/introduction.adoc[]
+
+* xref:jpa.adoc[]
+** xref:jpa/getting-started.adoc[]
 ** xref:repositories/core-concepts.adoc[]
 ** xref:repositories/definition.adoc[]
 ** xref:repositories/create-instances.adoc[]
-** xref:repositories/query-methods-details.adoc[]
-** xref:repositories/projections.adoc[]
-** xref:repositories/custom-implementations.adoc[]
-** xref:repositories/core-domain-events.adoc[]
-** xref:repositories/core-extensions.adoc[]
-** xref:repositories/null-handling.adoc[]
-** xref:repositories/query-keywords-reference.adoc[]
-** xref:repositories/query-return-types-reference.adoc[]
-* xref:jpa.adoc[]
-** xref:jpa/configuration.adoc[]
 ** xref:jpa/entity-persistence.adoc[]
+** xref:repositories/query-methods-details.adoc[]
 ** xref:jpa/query-methods.adoc[]
+** xref:repositories/projections.adoc[]
 ** xref:jpa/stored-procedures.adoc[]
 ** xref:jpa/specifications.adoc[]
-** xref:query-by-example.adoc[]
+** xref:repositories/query-by-example.adoc[]
 ** xref:jpa/transactions.adoc[]
 ** xref:jpa/locking.adoc[]
 ** xref:auditing.adoc[]
-** xref:jpa/misc-context.adoc[]
 ** xref:jpa/misc-merging-persistence-units.adoc[]
 ** xref:jpa/jpd-misc-cdi-integration.adoc[]
+** xref:repositories/custom-implementations.adoc[]
+** xref:repositories/core-domain-events.adoc[]
+** xref:repositories/null-handling.adoc[]
+** xref:repositories/core-extensions.adoc[]
+** xref:repositories/query-keywords-reference.adoc[]
+** xref:repositories/query-return-types-reference.adoc[]
 ** xref:jpa/faq.adoc[]
 ** xref:jpa/glossary.adoc[]
+
 * xref:envers.adoc[]
 ** xref:envers/introduction.adoc[]
 ** xref:envers/configuration.adoc[]
 ** xref:envers/usage.adoc[]
+
 * https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

src/main/antora/modules/ROOT/pages/jpa.adoc

@@ -2,5 +2,5 @@
 = JPA
 :page-section-summary-toc: 1
 
-This chapter points out the specialties for repository support for JPA. This builds on the core repository support explained in xref:repositories/introduction.adoc[Working with Spring Data Repositories]. Make sure you have a sound understanding of the basic concepts explained there.
+This chapter points out the specialties for repository support for JPA. This builds on the core repository support explained in xref:repositories.adoc[Working with Spring Data Repositories]. Make sure you have a sound understanding of the basic concepts explained there.
 

src/main/antora/modules/ROOT/pages/jpa/configuration.adoc

@@ -0,0 +1,67 @@
+[[jpa.getting-started]]
+= Getting Started
+
+An easy way to bootstrap setting up a working environment is to create a Spring-based project via https://start.spring.io/#!type=maven-project&dependencies=h2,data-jpa[start.spring.io] or create a Spring project in https://spring.io/tools[Spring Tools].
+
+[[jpa.examples-repo]]
+== Examples Repository
+
+The GitHub https://github.com/spring-projects/spring-data-examples[spring-data-examples repository] hosts several examples that you can download and play around with to get a feel for how the library works.
+
+[[redis.hello-world]]
+== Hello World
+
+Let's start with a simple entity and its corresponding repository:
+
+[source,java]
+----
+@Entity
+class Person {
+
+  @Id @GeneratedValue(strategy = GenerationType.AUTO)
+  private Long id;
+  private String name;
+
+  // getters and setters ommited for brevity
+}
+
+interface PersonRepository extends Repository<Person, Long> {
+
+  Person save(Person person);
+
+  Optional<Person> findById(long id);
+}
+----
+
+Create the main application to run, as the following example shows:
+
+[source,java]
+----
+@SpringBootApplication
+public class DemoApplication {
+
+  public static void main(String[] args) {
+    SpringApplication.run(DemoApplication.class, args);
+  }
+
+  @Bean
+  CommandLineRunner runner(PersonRepository repository) {
+    return args -> {
+
+      Person person = new Person();
+      person.setName("John");
+
+      repository.save(person);
+      Person saved = repository.findById(person.getId()).orElseThrow(NoSuchElementException::new);
+    };
+  }
+}
+----
+
+Even in this simple example, there are a few notable things to point out:
+
+* Repository instances are automatically implemented.
+When used as parameters of `@Bean` methods, these will be autowired without further need for annotations.
+* The basic repository extends `Repository`.
+We suggest to consider how much API surface you want to expose towards your application.
+More complex repository interfaces are `ListCrudRepository` or `JpaRepository`.

src/main/antora/modules/ROOT/pages/jpa/getting-started.adoc

@@ -1,5 +1,5 @@
 [[jpa.query-methods]]
-= Query Methods
+= JPA Query Methods
 
 This section describes the various ways to create a query with Spring Data JPA.
 
@@ -357,9 +357,9 @@ This is a lighter variant than paging because it does not require the total resu
 3. <<repositories.scrolling.keyset,Keyset-baset scrolling>>.
 This method avoids https://use-the-index-luke.com/no-offset[the shortcomings of offset-based result retrieval by leveraging database indexes].
 
-Read more on xref:repositories/query-methods-details.adoc#repositories.scrolling.guidance,which method to use best>> for your particular arrangement.
+Read more on <<repositories.scrolling.guidance,which method to use best>> for your particular arrangement.
 
-You can use the Scroll API with query methods, xref:query-by-example.adoc[Query-by-Example], and xref:repositories/core-extensions.adoc#core.extensions.querydsl[Querydsl].
+You can use the Scroll API with query methods, xref:repositories/query-by-example.adoc[Query-by-Example], and xref:repositories/core-extensions.adoc#core.extensions.querydsl[Querydsl].
 
 NOTE: Scrolling with String-based query methods is not yet supported.
 Scrolling is also not supported using stored `@Procedure` query methods.
@@ -432,7 +432,7 @@ Another use case for the `#{#entityName}` expression in a query string is if you
 @MappedSuperclass
 public abstract class AbstractMappedType {
   …
-  String attribute
+  String attribute;
 }
 
 @Entity
@@ -507,7 +507,7 @@ But sometimes, your query may simply be too complicated for the techniques offer
 In that situation, consider:
 
 * If you haven't already, simply write the query yourself using xref:jpa/query-methods.adoc#jpa.query-methods.at-query[`@Query`].
-* If that doesn't fit your needs, consider implementing a xref:repositories/custom-implementations.adoc#repositories.custom-implementations[custom implementation]. This lets you register a method in your repository while leaving the implementation completely up to you. This gives you the ability to:
+* If that doesn't fit your needs, consider implementing a xref:repositories/custom-implementations.adoc[custom implementation]. This lets you register a method in your repository while leaving the implementation completely up to you. This gives you the ability to:
 ** Talk directly to the `EntityManager` (writing pure HQL/JPQL/EQL/native SQL or using the *Criteria API*)
 ** Leverage Spring Framework's `JdbcTemplate` (native SQL)
 ** Use another 3rd-party database toolkit.