239 lines
7.3 KiB
Markdown
239 lines
7.3 KiB
Markdown
<p align="center">
|
||
<img alt="Spring Doc Resources" title="Spring Doc Resources" src="https://i.imgur.com/fGi6EaT.png" width="450">
|
||
</p>
|
||
|
||
This project generates and packages the static resources that Spring uses for document production.
|
||
|
||
## Maven build integration
|
||
|
||
You can use the [Asciidoctor Maven plugin](https://github.com/asciidoctor/asciidoctor-maven-plugin)
|
||
to generate your documentation.
|
||
|
||
You first need to declare this project as a dependency:
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>io.spring.docresources</groupId>
|
||
<artifactId>spring-doc-resources</artifactId>
|
||
<version>${docs.resources.version}</version>
|
||
<type>zip</type>
|
||
<optional>true</optional>
|
||
</dependency>
|
||
```
|
||
|
||
Unpack the resources and the actual asciidoc documents in a specific build directory:
|
||
|
||
```xml
|
||
<plugins>
|
||
<plugin>
|
||
<groupId>org.apache.maven.plugins</groupId>
|
||
<artifactId>maven-dependency-plugin</artifactId>
|
||
<executions>
|
||
<execution>
|
||
<id>unpack-doc-resources</id>
|
||
<goals>
|
||
<goal>unpack-dependencies</goal>
|
||
</goals>
|
||
<phase>generate-resources</phase>
|
||
<configuration>
|
||
<includeGroupIds>io.spring.docresources</includeGroupIds>
|
||
<includeArtifactIds>spring-doc-resources</includeArtifactIds>
|
||
<includeTypes>zip</includeTypes>
|
||
<excludeTransitive>true</excludeTransitive>
|
||
<outputDirectory>${project.build.directory}/refdocs/</outputDirectory>
|
||
</configuration>
|
||
</execution>
|
||
</executions>
|
||
</plugin>
|
||
<plugin>
|
||
<groupId>org.apache.maven.plugins</groupId>
|
||
<artifactId>maven-resources-plugin</artifactId>
|
||
<executions>
|
||
<execution>
|
||
<id>copy-asciidoc-resources</id>
|
||
<phase>generate-resources</phase>
|
||
<goals>
|
||
<goal>copy-resources</goal>
|
||
</goals>
|
||
<configuration>
|
||
<outputDirectory>${project.build.directory}/refdocs/</outputDirectory>
|
||
<resources>
|
||
<resource>
|
||
<directory>src/main/asciidoc</directory>
|
||
<filtering>false</filtering>
|
||
</resource>
|
||
</resources>
|
||
</configuration>
|
||
</execution>
|
||
</executions>
|
||
</plugin>
|
||
</plugins>
|
||
```
|
||
|
||
Finally, launch the documentation generation process; default output location is `target/generated-docs/`:
|
||
|
||
```xml
|
||
<plugin>
|
||
<groupId>org.asciidoctor</groupId>
|
||
<artifactId>asciidoctor-maven-plugin</artifactId>
|
||
<configuration>
|
||
<sourceDirectory>${refdocs.build.directory}</sourceDirectory>
|
||
<attributes>
|
||
// Add attributes generated by the build
|
||
<spring-project-docs-version>${revision}</spring-boot-docs-version>
|
||
<spring-version>${spring.version}</spring-version>
|
||
// Add locations of code snippets to include in the documentation
|
||
<sources-root>${project.basedir}/src/</sources-root>
|
||
</attributes>
|
||
</configuration>
|
||
<executions>
|
||
<execution>
|
||
<id>generate-html-documentation</id>
|
||
<phase>prepare-package</phase>
|
||
<goals>
|
||
<goal>process-asciidoc</goal>
|
||
</goals>
|
||
<configuration>
|
||
<backend>html5</backend>
|
||
<sourceHighlighter>highlight.js</sourceHighlighter>
|
||
<doctype>book</doctype>
|
||
<attributes>
|
||
// these attributes are required to use the doc resources
|
||
<docinfo>shared</docinfo>
|
||
<stylesdir>css/</stylesdir>
|
||
<stylesheet>spring.css</stylesheet>
|
||
<linkcss>true</linkcss>
|
||
<icons>font</icons>
|
||
<highlightjsdir>js/highlight</highlightjsdir>
|
||
<highlightjs-theme>atom-one-dark-reasonable</highlightjs-theme>
|
||
</attributes>
|
||
</configuration>
|
||
</execution>
|
||
</executions>
|
||
</plugin>
|
||
```
|
||
|
||
|
||
## Gradle build integration
|
||
|
||
You can use the [Asciidoctor Gradle plugin](https://asciidoctor.org/docs/asciidoctor-gradle-plugin/)
|
||
to generate your documentation.
|
||
|
||
```groovy
|
||
// declare a configuration for documentation resources
|
||
configurations {
|
||
docs
|
||
}
|
||
|
||
dependencies {
|
||
docs "io.spring.docresources:spring-doc-resources:${docResourcesVersion}@zip"
|
||
}
|
||
|
||
task prepareAsciidocBuild(type: Sync) {
|
||
dependsOn configurations.docs
|
||
// copy doc resources
|
||
from {
|
||
configurations.docs.collect { zipTree(it) }
|
||
}
|
||
// and doc sources
|
||
from "src/docs/asciidoc/"
|
||
// to a build directory of your choice
|
||
into "$buildDir/asciidoc/build"
|
||
}
|
||
|
||
asciidoctor {
|
||
// run asciidoctor from that directory
|
||
sourceDir "$buildDir/asciidoc/build"
|
||
sources {
|
||
include '*.adoc'
|
||
}
|
||
resources {
|
||
from(sourceDir) {
|
||
include 'images/*', 'css/**', 'js/**'
|
||
}
|
||
}
|
||
logDocuments = true
|
||
backends = ["html5"]
|
||
options doctype: 'book', eruby: 'erubis'
|
||
attributes 'docinfo': 'shared',
|
||
// use provided stylesheet
|
||
stylesdir: "css/",
|
||
stylesheet: 'spring.css',
|
||
'linkcss': true,
|
||
'icons': 'font',
|
||
// use provided highlighter
|
||
'source-highlighter=highlight.js',
|
||
'highlightjsdir=js/highlight',
|
||
'highlightjs-theme=atom-one-dark-reasonable'
|
||
}
|
||
|
||
asciidoctor.dependsOn prepareAsciidocBuild
|
||
```
|
||
|
||
## Limitations
|
||
|
||
### Code samples
|
||
|
||
When including code samples in the documentation, their location must not rely on relative paths,
|
||
as the actual documentation build happens within the `build`/`target` folder.
|
||
To work around that limitation, the build should introduce an attribute pointing to a particular
|
||
location within project sources, from which code samples can be resolved.
|
||
|
||
### DocInfo files
|
||
|
||
To get the dynamic table of contents to work correctly, you need to set the `docinfo` attribute to `shared`, thus: `:docinfo: shared`.
|
||
Bear in mind that, if you set the attribute in your build, it overrides the value in your Asciidoc files.
|
||
You may still want to set the attribute in your Asciidoc files, though, if you generate files with the `asciidoctor` command for testing.
|
||
You can also use `private` docinfo particular to asciidoc documents (see [docinfo documentation](https://asciidoctor.org/docs/user-manual/#naming-docinfo-files)).
|
||
|
||
|
||
## Distribution Zip
|
||
|
||
The final distribution zip file contains the following:
|
||
|
||
```
|
||
|- docinfo.html, docinfo-footer.html (shared docinfo HTML files)
|
||
|- css/** (stylesheets)
|
||
|– js
|
||
|- tocbot/** (navigation in table of contents)
|
||
|- highlight/** (code highlighting)
|
||
```
|
||
|
||
You should unzip the whole archive at the top of your Asciidoc hierarchy (typically `src/main/asciidoc` and typically in the same directory as `index.adoc`).
|
||
|
||
CAUTION: You cannot let Asciidoctor generate its output and then move the files. The files have to be in position when Asciidoctor runs.
|
||
|
||
|
||
## Doc Resources
|
||
|
||
This project contains the following:
|
||
|
||
* `/src/main/sass/**`: The stylesheet for the HTML versions of the Spring reference guides, generated from SASS files.
|
||
* `/src/main/resources/js/**`: Javascript libraries for the Table of Contents and code hilighting.
|
||
* `/src/main/resources/*.html`: The custom [Asciidoctor docinfo files](https://asciidoctor.org/docs/user-manual/#docinfo-file).
|
||
* `build.gradle`: The Gradle build file for this project.
|
||
* `gulpfile.js`: The Gulp build that compiles sources into static files
|
||
* `package.json`: The dependencies for the NPM-based build
|
||
* `README.md`: This file.
|
||
|
||
## Building the project
|
||
|
||
Running `./gradlew distZip` will build and package the asciidoctor theme in a zip file in `build/distributions`.
|
||
You can also publish that artifact to your local maven repository for testing with `./gradlew publishToMavenLocal`.
|
||
|
||
When working on the project, one can run the following command:
|
||
|
||
```
|
||
$ ./gradlew gulp_dev
|
||
```
|
||
|
||
This will start a local server on `http://localhost:8080`, watch files under `src/**` and rebuild automatically.
|
||
Please consider installing [the Livereload browser extension](http://livereload.com/) for a better experience.
|
||
|
||
You can also install the Gulp CLI and directly run build commands:
|
||
|
||
```
|
||
$ npm i -g gulp-cli
|
||
$ gulp dev
|
||
```
|