jlengrand/picocli
1
0
Fork 0
mirror of https://github.com/jlengrand/picocli.git synced 2026-03-10 08:41:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

[#299][#459] update examples and picocli-codegen README

Browse Source
This commit is contained in:
Remko Popma
2020-02-11 19:52:54 +09:00
parent 3274eb16ca
commit 40bb7e9a87
2 changed files with 59 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
picocli-codegen/README.adoc
View File

@@ -548,13 +548,13 @@ task generateManpageAsciiDoc(type: JavaExec) {
description = "Generate AsciiDoc manpage"
classpath(configurations.compile, configurations.annotationProcessor, sourceSets.main.runtimeClasspath)
main 'picocli.codegen.docgen.manpage.ManPageGenerator'
args mainClassName, "--outdir=${project.buildDir}/generated/docs", "-v" //, "--template-dir=src/docs/mantemplates"
args mainClassName, "--outdir=${project.buildDir}/generated-picocli-docs", "-v" //, "--template-dir=src/docs/mantemplates"
}
apply plugin: 'org.asciidoctor.convert'
asciidoctor {
dependsOn(generateManpageAsciiDoc)
sourceDir = file("${project.buildDir}/generated/docs")
sourceDir = file("${project.buildDir}/generated-picocli-docs")
outputDir = file("${project.buildDir}/docs")
logDocuments = true
backends 'manpage', 'html5'
@@ -562,25 +562,11 @@ asciidoctor {
----
The `generateManpageAsciiDoc` task generates `<cmd>.adoc` files with doctype `manpage` in `build/generated/docs` for each command and subcommand.
The `generateManpageAsciiDoc` task generates `<cmd>.adoc` files with doctype `manpage` in `build/generated-picocli-docs` for each command and subcommand.
The `asciidoctor` task converts the generated `<cmd>.adoc` files in `build/generated/docs` to `<cmd>.1` manpage files in `build/docs/manpage/`, and to `<cmd>.html` HTML files in `build/docs/html5/`.
The `asciidoctor` task converts the generated `<cmd>.adoc` files in `build/generated-picocli-docs` to `<cmd>.1` manpage files in `build/docs/manpage/`, and to `<cmd>.html` HTML files in `build/docs/html5/`.
You could then use the Gradle `distribution` plugin to include the generated manpage files in the distribution archive:
[source,groovy]
----
apply plugin: "distribution"
distributions {
main {
contents {
from ("${project.buildDir}/docs/manpage") {
into('docs')
}
}
}
}
----
See the link:https://github.com/remkop/picocli/tree/master/picocli-examples/generate-man-pages/example-gradle-project[example-gradle-project] in the `picocli-examples` module for a full working example.
=== Maven Example
@@ -614,7 +600,7 @@ Note that the `picocli-codegen` module is only added as a dependency for the `ex
<includePluginDependencies>true</includePluginDependencies>
<mainClass>picocli.codegen.docgen.manpage.ManPageGenerator</mainClass>
<arguments>
<argument>--outdir=target/generated/docs</argument>
<argument>--outdir=${project.build.directory}/generated-picocli-docs</argument>
<argument>com.your.package.YourCommand1</argument>
<argument>com.your.package.YourCommand2</argument>
</arguments>
@@ -628,10 +614,45 @@ Note that the `picocli-codegen` module is only added as a dependency for the `ex
</dependency>
</dependencies>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.6.0</version>
<executions>
<execution>
<id>output-html</id>
<phase>process-classes</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceHighlighter>coderay</sourceHighlighter>
<backend>html5</backend>
</configuration>
</execution>
<execution>
<id>output-manpage</id>
<phase>process-classes</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<sourceHighlighter>coderay</sourceHighlighter>
<backend>manpage</backend>
</configuration>
</execution>
</executions>
<configuration>
<sourceDirectory>${project.build.directory}/generated-picocli-docs</sourceDirectory>
</configuration>
</plugin>
</plugins>
</build>
----
See the link:https://github.com/remkop/picocli/tree/master/picocli-examples/generate-man-pages/example-maven-project[example-maven-project] in the `picocli-examples` module for a full working example.
=== Customizing with Templates
The generated man page is very similar to the online help generated by the command itself when a user specifies the `--help` option.
You may want to add more details or extra sections to the man page.

20
picocli-examples/generate-man-pages/example-gradle-project/build.gradle
View File

@@ -47,15 +47,31 @@ task generateManpageAsciiDoc(type: JavaExec) {
description = "Generate AsciiDoc manpage"
classpath(configurations.compile, configurations.annotationProcessor, sourceSets.main.runtimeClasspath)
main 'picocli.codegen.docgen.manpage.ManPageGenerator'
args project.ext.mainClassName, "--outdir=${project.buildDir}/generated/docs", "-v", "--template-dir=src/docs/mantemplates"
args project.ext.mainClassName, "--outdir=${project.buildDir}/generated-picocli-docs", "-v", "--template-dir=src/docs/mantemplates"
}
apply plugin: 'org.asciidoctor.convert'
asciidoctor {
dependsOn(generateManpageAsciiDoc)
sourceDir = file("${project.buildDir}/generated/docs")
sourceDir = file("${project.buildDir}/generated-picocli-docs")
outputDir = file("${project.buildDir}/docs")
logDocuments = true
backends 'manpage', 'html5'
}
assemble.dependsOn(asciidoctor)
// We can now use the Gradle `distribution` plugin to include
// the generated manpage files in the distribution archive:
apply plugin: "distribution"
distributions {
main {
contents {
from ("${project.buildDir}/docs/manpage") {
into('man')
}
from ("${project.buildDir}/docs/html5") {
into('docs')
}
}
}
}