Skip to content

Commit 1593ee8

Browse files
jvalkealjvalkeal
committed
Update docs
- Polish pom - Version command - Theming - Templating - Relates #354
1 parent 7e2a44f commit 1593ee8

File tree

2 files changed

+109
-22
lines changed

2 files changed

+109
-22
lines changed

‎spring-shell-docs/pom.xml‎

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -100,25 +100,24 @@
100100
</plugin>
101101

102102
<!-- ASCIIDOC -->
103-
104103
<plugin>
105-
<groupId>com.googlecode.maven-download-plugin</groupId>
106-
<artifactId>download-maven-plugin</artifactId>
107-
<executions>
108-
<execution>
109-
<id>unpack-doc-resources</id>
110-
<phase>generate-resources</phase>
111-
<goals>
112-
<goal>wget</goal>
113-
</goals>
114-
<configuration>
115-
<url>https://repo.spring.io/release/io/spring/docresources/spring-doc-resources/${spring-doc-resources.version}/spring-doc-resources-${spring-doc-resources.version}.zip</url>
116-
<unpack>true</unpack>
117-
<outputDirectory>${project.build.directory}/refdocs/</outputDirectory>
118-
</configuration>
119-
</execution>
120-
</executions>
121-
</plugin>
104+
<groupId>com.googlecode.maven-download-plugin</groupId>
105+
<artifactId>download-maven-plugin</artifactId>
106+
<executions>
107+
<execution>
108+
<id>unpack-doc-resources</id>
109+
<phase>generate-resources</phase>
110+
<goals>
111+
<goal>wget</goal>
112+
</goals>
113+
<configuration>
114+
<url>https://repo.spring.io/release/io/spring/docresources/spring-doc-resources/${spring-doc-resources.version}/spring-doc-resources-${spring-doc-resources.version}.zip</url>
115+
<unpack>true</unpack>
116+
<outputDirectory>${project.build.directory}/refdocs/</outputDirectory>
117+
</configuration>
118+
</execution>
119+
</executions>
120+
</plugin>
122121
<plugin>
123122
<groupId>org.apache.maven.plugins</groupId>
124123
<artifactId>maven-resources-plugin</artifactId>

‎spring-shell-docs/src/main/asciidoc/using-spring-shell.adoc‎

Lines changed: 92 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ This section describes how to use Spring Shell.
66

77
[IMPORTANT]
88
====
9-
_Spring Shell 3.x_ is a major rework to bring codebase up-to-date with
9+
_Spring Shell 2.1.x_ is a major rework to bring codebase up-to-date with
1010
existing _Spring Boot_ versions, adding new features and especially
1111
making it work with _GraalVM_ which makes command-line applications much
1212
more relevant on a java space. Moving to new major version also allows
@@ -888,9 +888,46 @@ working with non-interactive mode.
888888

889889
Currently only implementation is for _bash_ which works with `bash` sub-command.
890890

891+
==== Version
892+
893+
The `version` command shows existing _build_ and _git_ info by integrating into
894+
Boot's `BuildProperties` and `GitProperties` if those exists in a shell app.
895+
On default only version info is shown and other can be enabled via configuration
896+
options.
897+
898+
Settings are under `spring.shell.command.version` where you can use `enabled` to
899+
disable command and optionally define your own template with `template`. Options
900+
`show-build-artifact`, `show-build-group`, `show-build-name`, `show-build-time`,
901+
`show-build-version`, `show-git-branch`, `show-git-commit-id`,
902+
`show-git-short-commit-id` and `show-git-commit-time` can be used to control
903+
fields in a default template.
904+
905+
Template default to `classpath:template/version-default.st` and you can define
906+
your own, for example having:
907+
908+
====
909+
[source]
910+
----
911+
<buildVersion>
912+
----
913+
====
914+
915+
Which would simply output something like:
916+
917+
====
918+
[source]
919+
----
920+
X.X.X
921+
----
922+
====
923+
924+
Attributes added to default template rendering are `buildVersion`, `buildGroup`,
925+
`buildGroup`, `buildName`, `buildTime`, `gitShortCommitId`, `gitCommitId`,
926+
`gitBranch` and `gitCommitTime`.
927+
891928
=== Interaction Mode
892929

893-
Starting from _3.x_ a build-in support has been added to distinguish between interactive
930+
Starting from _2.1.x_ a build-in support has been added to distinguish between interactive
894931
and non-interactive modes. This has been added so that it's easier to use shell as a
895932
simple command-line tool without requiring customisation to accomplish that.
896933

@@ -908,7 +945,7 @@ shell when particular command is available.
908945
[[native]]
909946
=== Native Support
910947

911-
Re-work with _3.x_ brings in an experimental support for compiling shell application
948+
Re-work with _2.1.x_ brings in an experimental support for compiling shell application
912949
into _native_ application with _GraalVM_ and _spring-native_. As underlying _jline_
913950
library works with _GraalVM_ most of a things should just work.
914951

@@ -937,6 +974,57 @@ Built-In Commands
937974
----
938975
====
939976

977+
[[styling]]
978+
=== Styling
979+
980+
Starting with _2.1.x_ there is a support for centrally handling styling and theming.
981+
There is a default theme named _default_ which can be changed using property
982+
`spring.shell.theme.name`.
983+
984+
To create a new theme register new `Theme` bean with custom `ThemeSettings` where
985+
you can tweak styles.
986+
987+
====
988+
[source, java]
989+
----
990+
@Configuration
991+
static class CustomThemeConfig {
992+
993+
@Bean
994+
public Theme myTheme() {
995+
return new Theme() {
996+
@Override
997+
public String getName() {
998+
return "mytheme";
999+
}
1000+
@Override
1001+
public ThemeSettings getSettings() {
1002+
return new MyThemeSettings();
1003+
}
1004+
};
1005+
}
1006+
}
1007+
1008+
static class MyThemeSettings extends ThemeSettings {
1009+
}
1010+
----
1011+
====
1012+
1013+
`ThemeResolver` can be used to resolve styles if you want to create
1014+
_jline_ styled strings programmatically.
1015+
1016+
====
1017+
[source, java]
1018+
----
1019+
@Autowired
1020+
private ThemeResolver themeResolver;
1021+
1022+
String resolvedStyle = themeResolver.resolveTag(TAG_TITLE);
1023+
AttributedStyle style = themeResolver.resolveStyle(resolvedStyle);
1024+
----
1025+
====
1026+
1027+
9401028
=== Customizing the Shell
9411029

9421030
[[overriding-or-disabling-built-in-commands]]
@@ -1078,7 +1166,7 @@ various `ShellRunner` implementations where candidate will be picked up.
10781166

10791167
[IMPORTANT]
10801168
====
1081-
This is a breaking change in `3.x` as previous shell versions had an confusing
1169+
This is a breaking change in `2.1.x` as previous shell versions had an confusing
10821170
logic how `ApplicationRunner` instances were used. These changes were made
10831171
to have a better support for interactive and non-interactive modes in a same
10841172
shell application as it's convenient to fully work on command-line and still

0 commit comments

Comments
 (0)