Documents conversion to Asciidoc format (#1746)

Purpose of this change is to make current documentation available at https://www.eclipse.org/eclipselink/documentation/ (section Guides) more flexible and easier to modify. Each guide is published there under separate maven module under org.eclipse.persistence.documentation which is new documentation parent. Main advantages of Asciidoc format are: easy modifications style is separated from the content various output formats available Each guide is located under <maven_module>/src/main/asciidoc which is default source directory for asciidoctor-maven-plugin. Expected main/entry document file name to each guide is main.adoc file. main.adoc contains common attributes and contains a lot of includes. All included images are in PNG format as GIFs are not accepted in case of PDF output. Current configuration generates HTML (Web), PDF (Printable), EPUB (e-book) outputs. Documentation guides are not build by default, but under doc Maven profile. See: mvn clean package -rf :org.eclipse.persistence.documentation -P docs Signed-off-by: Radek Felcman <radek.felcman@oracle.com>
eclipse-ee4j · Nov 29, 2022 · e941b3c · e941b3c
1 parent 0658775
commit e941b3c
Show file tree

Hide file tree

Showing 382 changed files with 63,886 additions and 0 deletions.
diff --git a/docs/docs.concepts/pom.xml b/docs/docs.concepts/pom.xml
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 
+    Copyright (c) 2022 Oracle and/or its affiliates. All rights reserved.
+ 
+    This program and the accompanying materials are made available under the
+    terms of the Eclipse Public License v. 2.0, which is available at
+    http://www.eclipse.org/legal/epl-2.0.
+ 
+    This Source Code may also be made available under the following Secondary
+    Licenses when the conditions for such availability set forth in the
+    Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
+    version 2 with the GNU Classpath Exception, which is available at
+    https://www.gnu.org/software/classpath/license.html.
+ 
+    SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ 
+-->
+<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/maven-v4_0_0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <name>Documentation - Concepts</name>
+    <description>EclipseLink Documentation for the WebSite - Concepts</description>
+    <groupId>org.eclipse.persistence</groupId>
+    <artifactId>org.eclipse.persistence.documentation.concepts</artifactId>
+    <version>4.0.0-SNAPSHOT</version>
+    <packaging>pom</packaging>
+
+    <parent>
+        <groupId>org.eclipse.persistence</groupId>
+        <artifactId>org.eclipse.persistence.documentation</artifactId>
+        <version>4.0.0-SNAPSHOT</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <build>
+        <plugins>
+            <plugin>
+                <artifactId>maven-resources-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-source-documents</id>
+                        <phase>generate-resources</phase>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>unpack-shared-docs</id>
+                        <phase>generate-resources</phase>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.asciidoctor</groupId>
+                <artifactId>asciidoctor-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>asciidoc-to-html</id>
+                        <phase>generate-resources</phase>
+                        <configuration>
+                            <outputFile>concepts.html</outputFile>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>asciidoc-to-html-img-text</id>
+                        <phase>generate-resources</phase>
+                    </execution>
+                    <execution>
+                        <id>asciidoc-to-pdf</id>
+                        <phase>generate-resources</phase>
+                        <configuration>
+                            <outputFile>concepts.pdf</outputFile>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>asciidoc-to-epub</id>
+                        <phase>generate-resources</phase>
+                        <configuration>
+                            <outputFile>concepts.epub</outputFile>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>
diff --git a/docs/docs.concepts/src/main/asciidoc/app_dev.adoc b/docs/docs.concepts/src/main/asciidoc/app_dev.adoc
@@ -0,0 +1,48 @@
+///////////////////////////////////////////////////////////////////////////////
+
+    Copyright (c) 2022 Oracle and/or its affiliates. All rights reserved.
+
+    This program and the accompanying materials are made available under the
+    terms of the Eclipse Public License v. 2.0, which is available at
+    http://www.eclipse.org/legal/epl-2.0.
+
+    This Source Code may also be made available under the following Secondary
+    Licenses when the conditions for such availability set forth in the
+    Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
+    version 2 with the GNU Classpath Exception, which is available at
+    https://www.gnu.org/software/classpath/license.html.
+
+    SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+
+///////////////////////////////////////////////////////////////////////////////
+
+:description: EclipseLink
+:keywords: eclipselink, java, jpa, persistence, concepts, orm, mapping
+
+== Understanding the Persistence Unit
+
+This chapter describes details about the persistence unit and the
+persistence layer.
+
+This chapter includes the following sections:
+
+* link:#APPDEV001[About the Persistence Unit]
+* link:#APPDEV002[Building and Using the Persistence Layer]
+* link:#APPDEV003[About Persisting Objects]
+* link:#APPDEV004[Migrating Applications to the EclipseLink Persistence Manager]
+* link:#APPDEV005[About Weaving]
+
+//About the Persistence Unit
+include::{rootdir}/app_dev001.adoc[]
+
+//Building and Using the Persistence Layer
+include::{rootdir}/app_dev002.adoc[]
+
+//About Persisting Objects
+include::{rootdir}/app_dev003.adoc[]
+
+//Migrating Applications to the EclipseLink Persistence Manager
+include::{rootdir}/app_dev004.adoc[]
+
+//About Weaving
+include::{rootdir}/app_dev005.adoc[]