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 io.spring.docresources spring-doc-resources ${docs.resources.version} zip true ``` Unpack the resources and the actual asciidoc documents in a specific build directory: ```xml org.apache.maven.plugins maven-dependency-plugin unpack-doc-resources unpack-dependencies generate-resources io.spring.docresources spring-doc-resources zip true ${project.build.directory}/refdocs/ org.apache.maven.plugins maven-resources-plugin copy-asciidoc-resources generate-resources copy-resources ${project.build.directory}/refdocs/ src/main/asciidoc false ``` Finally, launch the documentation generation process; default output location is `target/generated-docs/`: ```xml org.asciidoctor asciidoctor-maven-plugin ${refdocs.build.directory} // Add attributes generated by the build ${revision} ${spring.version} // Add locations of code snippets to include in the documentation ${project.basedir}/src/ generate-html-documentation prepare-package process-asciidoc html5 highlight.js book // these attributes are required to use the doc resources shared css/ spring.css true font js/highlight atom-one-dark-reasonable ``` ## 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 ```