Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document Gradle and Maven configuration for self-hosted documentation

Browse Source 
Update the README to describe how to include the generated documentation
in a project’s jar file so that it can be served as static content by,
for example, Spring Boot.

Closes gh-12
This commit is contained in:
Andy Wilkinson
2015-02-16 11:05:29 +00:00
parent 530a218ab4
commit f405848179
5 changed files with 115 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
README.md
View File

@@ -117,6 +117,21 @@ asciidoctor {
```
You may want to include the generated documentation in your project's jar file, for
example to have it [served as static content by Spring Boot][12]. You can do so by
configuring the `jar` task to depend on the `asciidoctor` task and to copy the
generated documentation into the jar's `static` directory:
```groovy
jar {
dependsOn asciidoctor
from ("${asciidoctor.outputDir}/html5") {
into 'static/docs'
}
}
```
#### Maven configuration
You can look at either samples' `pom.xml` file to see the required configuration. The key
@@ -176,7 +191,48 @@ access to the generated snippets:
</execution>
</executions>
</plugin>
```
You may want to include the generated documentation in your project's jar file, for
example to have it [served as static content by Spring Boot][12]. You can do so by
changing the configuration of the Asciidoctor plugin so that it runs in the
`prepare-package` phase and then configuring Maven's resources plugin to copy the
generated documentation into a location where it'll be included in the project's jar:
```xml
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.2</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase>
<!-- … -->
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>2.7</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
<resources>
<resource>
<directory>${project.build.directory}/generated-docs</directory>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
```
### Programatically generated snippets
@@ -282,3 +338,4 @@ To learn more, take a look at the accompanying sample projects:
[9]: https://speakerdeck.com/ankinson/documenting-restful-apis
[10]: https://build.spring.io/plugins/servlet/buildStatusImage/SRD-PUB (Build status)
[11]: https://build.spring.io/browse/SRD-PUB
[12]: http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-spring-mvc-static-content

7
rest-notes-spring-data-rest/build.gradle
View File

@@ -51,6 +51,13 @@ asciidoctor {
dependsOn test
}
jar {
dependsOn asciidoctor
from ("${asciidoctor.outputDir}/html5") {
into 'static/docs'
}
}
task wrapper(type: Wrapper) {
gradleVersion = '2.1'
}

23
rest-notes-spring-data-rest/pom.xml
View File

@@ -79,7 +79,7 @@
<executions>
<execution>
<id>generate-docs</id>
<phase>package</phase>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
@@ -93,6 +93,27 @@
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>2.7</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
<resources>
<resource>
<directory>${project.build.directory}/generated-docs</directory>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

7
rest-notes-spring-hateoas/build.gradle
View File

@@ -53,6 +53,13 @@ asciidoctor {
dependsOn test
}
jar {
dependsOn asciidoctor
from ("${asciidoctor.outputDir}/html5") {
into 'static/docs'
}
}
task wrapper(type: Wrapper) {
gradleVersion = '2.1'
}

23
rest-notes-spring-hateoas/pom.xml
View File

@@ -95,7 +95,7 @@
<executions>
<execution>
<id>generate-docs</id>
<phase>package</phase>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
@@ -109,6 +109,27 @@
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>2.7</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/static/docs</outputDirectory>
<resources>
<resource>
<directory>${project.build.directory}/generated-docs</directory>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>