diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
new file mode 100644
index 000000000..e4d12b67e
--- /dev/null
+++ b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,31 @@
+name: Deploy Docs
+on:
+ push:
+ branches-ignore: [ gh-pages ]
+ tags: '**'
+ repository_dispatch:
+ types: request-build-reference # legacy
+ #schedule:
+ #- cron: '0 10 * * *' # Once per day at 10am UTC
+ workflow_dispatch:
+permissions:
+ actions: write
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+ with:
+ ref: docs-build
+ fetch-depth: 1
+ - name: Dispatch (partial build)
+ if: github.ref_type == 'branch'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
+ - name: Dispatch (full build)
+ if: github.ref_type == 'tag'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)
diff --git a/spring-shell-docs/.github/workflows/deploy-docs.yml b/spring-shell-docs/.github/workflows/deploy-docs.yml
new file mode 100644
index 000000000..1435fc217
--- /dev/null
+++ b/spring-shell-docs/.github/workflows/deploy-docs.yml
@@ -0,0 +1,33 @@
+name: Deploy Docs
+on:
+ push:
+ branches-ignore: [ gh-pages ]
+ tags: '**'
+ repository_dispatch:
+ types: request-build-reference # legacy
+ #schedule:
+ #- cron: '0 10 * * *' # Once per day at 10am UTC
+ workflow_dispatch:
+permissions:
+ actions: write
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ # FIXME enable when pushed to spring-projects
+ # if: github.repository_owner == 'spring-projects'
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+ with:
+ ref: docs-build
+ fetch-depth: 1
+ - name: Dispatch (partial build)
+ if: github.ref_type == 'branch'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
+ - name: Dispatch (full build)
+ if: github.ref_type == 'tag'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)
diff --git a/spring-shell-docs/antora-playbook.yml b/spring-shell-docs/antora-playbook.yml
new file mode 100644
index 000000000..510665807
--- /dev/null
+++ b/spring-shell-docs/antora-playbook.yml
@@ -0,0 +1,41 @@
+# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2
+#
+# The purpose of this Antora playbook is to build the docs in the current branch.
+antora:
+ extensions:
+ - '@springio/antora-extensions/partial-build-extension'
+ - require: '@springio/antora-extensions/latest-version-extension'
+ - require: '@springio/antora-extensions/inject-collector-cache-config-extension'
+ - '@antora/collector-extension'
+ - '@antora/atlas-extension'
+ - require: '@springio/antora-extensions/root-component-extension'
+ root_component_name: 'shell'
+site:
+ title: Spring Shell
+ url: https://docs.spring.io/spring-shell/reference/
+content:
+ sources:
+ - url: ./..
+ branches: HEAD
+ start_path: spring-shell-docs
+ worktrees: true
+asciidoc:
+ attributes:
+ page-stackoverflow-url: https://stackoverflow.com/tags/spring-shell
+ page-pagination: ''
+ hide-uri-scheme: '@'
+ tabs-sync-option: '@'
+ chomp: 'all'
+ extensions:
+ - '@asciidoctor/tabs'
+ - '@springio/asciidoctor-extensions'
+ sourcemap: true
+urls:
+ latest_version_segment: ''
+runtime:
+ log:
+ failure_level: warn
+ format: pretty
+ui:
+ bundle:
+ url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.4/ui-bundle.zip
\ No newline at end of file
diff --git a/spring-shell-docs/antora.yml b/spring-shell-docs/antora.yml
new file mode 100644
index 000000000..9b34c10b0
--- /dev/null
+++ b/spring-shell-docs/antora.yml
@@ -0,0 +1,20 @@
+name: shell
+version: true
+title: Spring Shell
+nav:
+ - modules/ROOT/nav.adoc
+ext:
+ collector:
+ run:
+ command: gradlew -q "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-shell-docs:generateAntoraYml
+ local: true
+ scan:
+ dir: ./build/generated-antora-resources
+
+asciidoc:
+ attributes:
+ attribute-missing: 'warn'
+ # FIXME: the copyright is not removed
+ # FIXME: The package is not renamed
+ chomp: 'all'
+ snippets: example$docs-src/test/java/org/springframework/shell/docs
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/assets/images/component-confirmation-1.svg b/spring-shell-docs/modules/ROOT/assets/images/component-confirmation-1.svg
new file mode 100644
index 000000000..32bd94cf1
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/assets/images/component-confirmation-1.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/assets/images/component-flow-conditional-1.svg b/spring-shell-docs/modules/ROOT/assets/images/component-flow-conditional-1.svg
new file mode 100644
index 000000000..9cf2e97d5
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/assets/images/component-flow-conditional-1.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/assets/images/component-flow-showcase-1.svg b/spring-shell-docs/modules/ROOT/assets/images/component-flow-showcase-1.svg
new file mode 100644
index 000000000..23363bb4a
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/assets/images/component-flow-showcase-1.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/assets/images/component-multi-select-1.svg b/spring-shell-docs/modules/ROOT/assets/images/component-multi-select-1.svg
new file mode 100644
index 000000000..a9928f51f
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/assets/images/component-multi-select-1.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/assets/images/component-path-input-1.svg b/spring-shell-docs/modules/ROOT/assets/images/component-path-input-1.svg
new file mode 100644
index 000000000..54f764029
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/assets/images/component-path-input-1.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/assets/images/component-path-search-1.svg b/spring-shell-docs/modules/ROOT/assets/images/component-path-search-1.svg
new file mode 100644
index 000000000..498b5be1f
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/assets/images/component-path-search-1.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/assets/images/component-single-select-1.svg b/spring-shell-docs/modules/ROOT/assets/images/component-single-select-1.svg
new file mode 100644
index 000000000..42f461122
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/assets/images/component-single-select-1.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/assets/images/component-text-input-1.svg b/spring-shell-docs/modules/ROOT/assets/images/component-text-input-1.svg
new file mode 100644
index 000000000..9f01dd37a
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/assets/images/component-text-input-1.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/examples/docs-src b/spring-shell-docs/modules/ROOT/examples/docs-src
new file mode 120000
index 000000000..dabb0e15a
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/examples/docs-src
@@ -0,0 +1 @@
+../../../src
\ No newline at end of file
diff --git a/spring-shell-docs/modules/ROOT/nav.adoc b/spring-shell-docs/modules/ROOT/nav.adoc
new file mode 100644
index 000000000..a1f181b82
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/nav.adoc
@@ -0,0 +1,86 @@
+* xref:index.adoc[Overview]
+* xref:getting-started.adoc[]
+* xref:using-shell-basics.adoc[]
+** xref:using-shell-basics-reading.adoc[]
+* xref:using-shell-commands.adoc[]
+** xref:using-shell-commands-registration.adoc[]
+** xref:using-shell-commands-registration-programmatic.adoc[]
+** xref:using-shell-commands-registration-annotation.adoc[]
+** xref:using-shell-commands-registration-legacyannotation.adoc[]
+** xref:using-shell-commands-organize.adoc[]
+** xref:using-shell-commands-availability.adoc[]
+** xref:using-shell-commands-exceptionhandling.adoc[]
+*** xref:using-shell-commands-exceptionhandling-resolving.adoc[]
+*** xref:using-shell-commands-exceptionhandling-mappings.adoc[]
+*** xref:using-shell-commands-exceptionhandling-annotation.adoc[]
+** xref:using-shell-commands-hidden.adoc[]
+** xref:using-shell-commands-helpoptions.adoc[]
+** xref:using-shell-commands-interactionmode.adoc[]
+** xref:using-shell-commands-builtin.adoc[]
+*** xref:using-shell-commands-builtin-help.adoc[]
+*** xref:using-shell-commands-builtin-clear.adoc[]
+*** xref:using-shell-commands-builtin-exit.adoc[]
+*** xref:using-shell-commands-builtin-stacktrace.adoc[]
+*** xref:using-shell-commands-builtin-script.adoc[]
+*** xref:using-shell-commands-builtin-history.adoc[]
+*** xref:using-shell-commands-builtin-completion.adoc[]
+*** xref:using-shell-commands-builtin-version.adoc[]
+** xref:using-shell-commands-writing.adoc[]
+* xref:using-shell-options.adoc[]
+** xref:using-shell-options-basics.adoc[]
+*** xref:using-shell-options-basics-programmatic.adoc[]
+*** xref:using-shell-options-basics-annotation.adoc[]
+*** xref:using-shell-options-basics-legacyannotation.adoc[]
+** xref:using-shell-options-short.adoc[]
+** xref:using-shell-options-arity.adoc[]
+** xref:using-shell-options-positional.adoc[]
+** xref:using-shell-options-optional.adoc[]
+** xref:using-shell-options-default.adoc[]
+** xref:using-shell-options-validation.adoc[]
+** xref:using-shell-options-label.adoc[]
+** xref:using-shell-options-types.adoc[]
+** xref:using-shell-options-naming.adoc[]
+* xref:using-shell-completion.adoc[]
+* xref:using-shell-building.adoc[]
+* xref:using-shell-components.adoc[]
+** xref:using-shell-components-flow.adoc[]
+** xref:using-shell-components-ui.adoc[]
+*** xref:using-shell-components-ui-render.adoc[]
+*** xref:using-shell-components-ui-stringinput.adoc[]
+*** xref:using-shell-components-ui-pathinput.adoc[]
+*** xref:using-shell-components-ui-pathsearch.adoc[]
+*** xref:using-shell-components-ui-confirmation.adoc[]
+*** xref:using-shell-components-ui-singleselect.adoc[]
+*** xref:using-shell-components-ui-multiselect.adoc[]
+* xref:using-shell-tui.adoc[]
+** xref:using-shell-tui-intro.adoc[]
+** xref:using-shell-tui-views.adoc[]
+*** xref:using-shell-tui-views-box.adoc[]
+*** xref:using-shell-tui-views-list.adoc[]
+* xref:using-shell-customization.adoc[]
+** xref:using-shell-customization-styling.adoc[]
+** xref:using-shell-customization-logging.adoc[]
+** xref:using-shell-customization-commandnotfound.adoc[]
+** xref:using-shell-customization-singlecommand.adoc[]
+* xref:using-shell-execution.adoc[]
+* xref:using-shell-testing.adoc[]
+** xref:using-shell-testing-basics.adoc[]
+** xref:using-shell-testing-settings.adoc[]
+* Appendices
+** xref:appendices-techical-intro.adoc[]
+*** xref:appendices-techical-intro-registration.adoc[]
+*** xref:appendices-techical-intro-parser.adoc[]
+*** xref:appendices-techical-intro-execution.adoc[]
+*** xref:appendices-techical-intro-commandcontext.adoc[]
+*** xref:appendices-techical-intro-commandcatalog.adoc[]
+*** xref:appendices-techical-intro-theming.adoc[]
+*** xref:appendices-techical-intro-searchalgorithm.adoc[]
+** xref:appendices-debugging.adoc[]
+** xref:appendices-tui.adoc[]
+*** xref:appendices-tui-control.adoc[]
+*** xref:appendices-tui-view.adoc[]
+*** xref:appendices-tui-eventloop.adoc[]
+*** xref:appendices-tui-screen.adoc[]
+*** xref:appendices-tui-keyhandling.adoc[]
+*** xref:appendices-tui-mousehandling.adoc[]
+*** xref:appendices-tui-catalog.adoc[]
\ No newline at end of file
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-debugging.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-debugging.adoc
similarity index 79%
rename from spring-shell-docs/src/main/asciidoc/appendices-debugging.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-debugging.adoc
index d78b03c78..fa1356c22 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-debugging.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-debugging.adoc
@@ -1,5 +1,6 @@
[appendix]
[#appendix-debugging]
-== Debugging
+= Debugging
+:page-section-summary-toc: 1
Please find more info about debugging from https://github.com/spring-projects/spring-shell/wiki/Debugging[project wiki].
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcatalog.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcatalog.adoc
similarity index 90%
rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcatalog.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcatalog.adoc
index 22c3f6e24..0cc61cec6 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcatalog.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcatalog.adoc
@@ -1,43 +1,41 @@
-=== Command Catalog
+[[command-catalog]]
+= Command Catalog
+
The `CommandCatalog` interface defines how command registrations exist in
a shell application. It is possible to dynamically register and de-register
commands, which gives flexibility for use cases where possible commands
come and go, depending on a shell's state. Consider the following example:
-====
[source, java, indent=0]
----
include::{snippets}/CommandCatalogSnippets.java[tag=snippet1]
----
-====
-==== Command Resolver
+[[command-resolver]]
+== Command Resolver
You can implement the `CommandResolver` interface and define a bean to dynamically
resolve mappings from a command's name to its `CommandRegistration` instances. Consider
the following example:
-====
[source, java, indent=0]
----
include::{snippets}/CommandCatalogSnippets.java[tag=snippet2]
----
-====
IMPORTANT: A current limitation of a `CommandResolver` is that it is used every time commands are resolved.
Thus, we advise not using it if a command resolution call takes a long time, as it would
make the shell feel sluggish.
-==== Command Catalog Customizer
+[[command-catalog-customizer]]
+== Command Catalog Customizer
You can use the `CommandCatalogCustomizer` interface to customize a `CommandCatalog`.
Its main use is to modify a catalog. Also, within `spring-shell` auto-configuration, this
interface is used to register existing `CommandRegistration` beans into a catalog.
Consider the following example:
-====
[source, java, indent=0]
----
include::{snippets}/CommandCatalogSnippets.java[tag=snippet3]
----
-====
You can create a `CommandCatalogCustomizer` as a bean, and Spring Shell handles the rest.
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcontext.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcontext.adoc
similarity index 86%
rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcontext.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcontext.adoc
index 8593a4dfe..9eb50a2d7 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-commandcontext.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-commandcontext.adoc
@@ -1,20 +1,19 @@
-=== Command Context
+[[command-context]]
+= Command Context
+:page-section-summary-toc: 1
+
The `CommandContext` interface gives access to a currently running
context. You can use it to get access to options:
-====
[source, java, indent=0]
----
include::{snippets}/CommandContextSnippets.java[tag=snippet1]
----
-====
If you need to print something into a shell, you can get a `Terminal`
and use its writer to print something:
-====
[source, java, indent=0]
----
include::{snippets}/CommandContextSnippets.java[tag=snippet2]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-execution.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-execution.adoc
similarity index 66%
rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-execution.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-execution.adoc
index 22fe4c020..954f83ce5 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-execution.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-execution.adoc
@@ -1,3 +1,6 @@
-=== Command Execution
+[[command-execution]]
+= Command Execution
+:page-section-summary-toc: 1
+
When command parsing has done its job and command registration has been resolved, command execution
does the hard work of running the code.
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-parser.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-parser.adoc
similarity index 72%
rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-parser.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-parser.adoc
index 1ecc76ae3..6d785205f 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-parser.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-parser.adoc
@@ -1,3 +1,6 @@
-=== Command Parser
+[[command-parser]]
+= Command Parser
+:page-section-summary-toc: 1
+
Before a command can be executed, we need to parse the command and whatever options the user may have provided. Parsing
comes between command registration and command execution.
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-registration.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-registration.adoc
similarity index 93%
rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-registration.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-registration.adoc
index 415461d31..416bf8918 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-registration.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-registration.adoc
@@ -1,16 +1,17 @@
[#appendix-tech-intro-registration]
-=== Command Registration
+= Command Registration
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Defining a command registration is a first step to introducing the structure of a command and its options
and parameters. This is loosely decoupled from what happens later, such as parsing command-line input and running
actual target code. Essentially, it is the definition of a command API that is shown to a user.
-==== Commands
+[[commands]]
+== Commands
A command in a `spring-shell` structure is defined as an array of commands. This yields a
structure similar to the following example:
-====
[source, bash]
----
command1 sub1
@@ -18,12 +19,12 @@ command2 sub1 subsub1
command2 sub2 subsub1
command2 sub2 subsub2
----
-====
NOTE: We do not currently support mapping commands to an explicit parent if sub-commands are defined.
For example, `command1 sub1` and `command1 sub1 subsub1` cannot both be registered.
-==== Interaction Mode
+[[interaction-mode]]
+== Interaction Mode
Spring Shell has been designed to work on two modes: interactive (which essentially
is a `REPL` where you have an active shell instance throughout a series of commands) and
non-interactive (where commands are executed one by one from a command line).
@@ -36,70 +37,63 @@ dictates the available information.
Also, being on an active `REPL` session may provide more information about what the user has been
doing within an active session.
-==== Options
+[[options]]
+== Options
Options can be defined as long and short, where the prefixing is `--` and `-`, respectively.
The following examples show long and short options:
-====
[source, java, indent=0]
----
include::{snippets}/CommandRegistrationSnippets.java[tag=snippet1]
----
-====
-====
[source, java, indent=0]
----
include::{snippets}/CommandRegistrationSnippets.java[tag=snippet2]
----
-====
-==== Target
+[[target]]
+== Target
The target defines the execution target of a command. It can be a method in a POJO,
a `Consumer`, or a `Function`.
-===== Method
+[[method]]
+=== Method
Using a `Method` in an existing POJO is one way to define a target.
Consider the following class:
-====
[source, java, indent=0]
----
include::{snippets}/CommandTargetSnippets.java[tag=snippet11]
----
-====
Given the existing class shown in the preceding listing, you can then register its method:
-====
[source, java, indent=0]
----
include::{snippets}/CommandTargetSnippets.java[tag=snippet12]
----
-====
-===== Function
+[[function]]
+=== Function
Using a `Function` as a target gives a lot of flexibility to handle what
happens in a command execution, because you can handle many things manually by using
a `CommandContext` given to a `Function`. The return type from a `Function` is
then what gets printed into the shell as a result. Consider the following example:
-====
[source, java, indent=0]
----
include::{snippets}/CommandTargetSnippets.java[tag=snippet2]
----
-====
-===== Consumer
+[[consumer]]
+=== Consumer
Using a `Consumer` is basically the same as using a `Function`, with the difference being
that there is no return type. If you need to print something into a shell,
you can get a reference to a `Terminal` from a context and print something
through it. Consider the following example:
-====
[source, java, indent=0]
----
include::{snippets}/CommandTargetSnippets.java[tag=snippet3]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-searchalgorithm.adoc
similarity index 92%
rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-searchalgorithm.adoc
index 5fa9492f5..a7f8ac7de 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-searchalgorithm.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-searchalgorithm.adoc
@@ -1,5 +1,6 @@
[#appendix-tech-intro-searchalgorithm]
-=== Search Algorithms
+= Search Algorithms
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
`SearchMatch` is an interface to match _text_ with a _pattern_. Match
@@ -8,7 +9,8 @@ contains info about match positions and overall score of a match.
https://github.com/junegunn/fzf[fzf].
-==== Implementations
+[[implementations]]
+== Implementations
*FuzzyMatchV2Search*
@@ -20,19 +22,18 @@ quickly finding paths.
Port of _fzf ExactMatchNaive_ algorithm. Simple exact match works more accurately
if you know what to search.
-==== SearchMatch
+[[searchmatch]]
+== SearchMatch
Algorithms and default syntax are hidden inside package protected classes
as we don't want to fully open these until we know API's are good to go
for longer support. You need to construct `SearchMatch` via its
build-in builder.
-====
[source, java, indent=0]
----
include::{snippets}/SearchAlgorithmsSnippets.java[tag=builder]
----
-====
It's possible to configure _case sensitivity_, on what _direction_ search
happens or if text should be _normilized_ before search happens. Normalization
@@ -55,11 +56,10 @@ below table.
|Items that include `stuff`
|===
-==== Examples
+[[examples]]
+== Examples
-====
[source, java, indent=0]
----
include::{snippets}/SearchAlgorithmsSnippets.java[tag=simple]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-theming.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-theming.adoc
similarity index 97%
rename from spring-shell-docs/src/main/asciidoc/appendices-techical-intro-theming.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-theming.adoc
index 15e4989bf..8320c47d7 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro-theming.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro-theming.adoc
@@ -1,5 +1,6 @@
[#appendix-tech-intro-theming]
-=== Theming
+= Theming
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Styling in a theming is provided by a use of a _AttributedString_ from `JLine`.
@@ -22,7 +23,6 @@ applied. Prefixing with `~` will resolve from JLine internal bsd color table.
If rgb format is expected and prefixed with either `x` or `#` a normal
hex format is used.
-====
[source, text]
----
fg-red
@@ -31,30 +31,25 @@ fg-rgb:red
fg-rgb:xff3333
fg-rgb:#ff3333
----
-====
If spec contains special names `default`, `bold`, `faint`, `italic`, `underline`, `blink`,
`inverse`, `inverse-neg`, `inverseneg`, `conceal`, `crossed-out`, `crossedout` or `hidden`
a style is changed accordingly with an existing color.
-====
[source, text]
----
bold
bold,fg:red
----
-====
If spec is a number or numbers separated with semicolon, format is a plain part of an ansi
ascii codes.
-====
[source, text]
----
31
31;1
----
-====
NOTE: JLine special mapping format which would resolve spec starting with dot can't be
used as we don't yet map those into Spring Shell styling names.
diff --git a/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro.adoc
new file mode 100644
index 000000000..4af2f9d7a
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-techical-intro.adoc
@@ -0,0 +1,14 @@
+[appendix]
+[#appendix-tech-intro]
+= Techical Introduction
+:page-section-summary-toc: 1
+
+This appendix contains information for developers and others who would like to know more about how Spring Shell
+works internally and what its design decisions are.
+
+
+
+
+
+
+
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-tui-catalog.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-tui-catalog.adoc
similarity index 85%
rename from spring-shell-docs/src/main/asciidoc/appendices-tui-catalog.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-tui-catalog.adoc
index 21b205c81..ee541b643 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-tui-catalog.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-tui-catalog.adoc
@@ -1,5 +1,7 @@
[#appendix-tui-catalog]
-=== Catalog App
+= Catalog App
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Catalog application is showing various ways how Terminal UI Framework can be used.
@@ -7,6 +9,7 @@ In this section we discuss how this application works. It can be considered to b
a reference application as it's using most of the features available and tries
to follow best practices.
-==== Create Scenario
+[[create-scenario]]
+== Create Scenario
Every `Scenario` essentially is a sample code of a `View` as that's what catalog
app demonstrates.
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-tui-control.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-tui-control.adoc
similarity index 80%
rename from spring-shell-docs/src/main/asciidoc/appendices-tui-control.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-tui-control.adoc
index 021b30a21..2e58764b6 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-tui-control.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-tui-control.adoc
@@ -1,5 +1,7 @@
[#appendix-tui-control]
-=== Control
+= Control
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
_Control_ draws something into a screen with a given bounds.
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-tui-eventloop.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-tui-eventloop.adoc
similarity index 80%
rename from spring-shell-docs/src/main/asciidoc/appendices-tui-eventloop.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-tui-eventloop.adoc
index 80d49f385..0a48a8c1e 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-tui-eventloop.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-tui-eventloop.adoc
@@ -1,5 +1,7 @@
[#appendix-tui-eventloop]
-=== EventLoop
+= EventLoop
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
_EventLoop_ is a central system handling eventing in a framework.
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-tui-keyhandling.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-tui-keyhandling.adoc
similarity index 74%
rename from spring-shell-docs/src/main/asciidoc/appendices-tui-keyhandling.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-tui-keyhandling.adoc
index 5f999c51f..7d6aa22e9 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-tui-keyhandling.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-tui-keyhandling.adoc
@@ -1,5 +1,7 @@
[#appendix-tui-keyhandling]
-=== Key Handling
+= Key Handling
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Handles incoming key events.
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-tui-mousehandling.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-tui-mousehandling.adoc
similarity index 74%
rename from spring-shell-docs/src/main/asciidoc/appendices-tui-mousehandling.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-tui-mousehandling.adoc
index 5fba7f7aa..14804df1b 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-tui-mousehandling.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-tui-mousehandling.adoc
@@ -1,5 +1,7 @@
[#appendix-tui-mousehandling]
-=== Mouse Handling
+= Mouse Handling
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Handles incoming mouse events.
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-tui-screen.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-tui-screen.adoc
similarity index 83%
rename from spring-shell-docs/src/main/asciidoc/appendices-tui-screen.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-tui-screen.adoc
index 6b38905a1..f7d697251 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-tui-screen.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-tui-screen.adoc
@@ -1,5 +1,7 @@
[#appendix-tui-screen]
-=== Screen
+= Screen
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
_Screen_ is an abstraction providing higher level concept to draw something
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-tui-view.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-tui-view.adoc
similarity index 81%
rename from spring-shell-docs/src/main/asciidoc/appendices-tui-view.adoc
rename to spring-shell-docs/modules/ROOT/pages/appendices-tui-view.adoc
index bc83a5aea..958581622 100644
--- a/spring-shell-docs/src/main/asciidoc/appendices-tui-view.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-tui-view.adoc
@@ -1,5 +1,7 @@
[#appendix-tui-view]
-=== View
+= View
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
_View_ extends _Control_ providing integration into event loop.
diff --git a/spring-shell-docs/modules/ROOT/pages/appendices-tui.adoc b/spring-shell-docs/modules/ROOT/pages/appendices-tui.adoc
new file mode 100644
index 000000000..2c7b353e1
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/pages/appendices-tui.adoc
@@ -0,0 +1,17 @@
+[appendix]
+[#appendix-tech-intro-tui]
+= Terminal UI
+:page-section-summary-toc: 1
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+This is a technical introduction to _UI Framework_.
+
+_UI Framework_ is a toolkit to build rich console apps.
+
+
+
+
+
+
+
diff --git a/spring-shell-docs/src/main/asciidoc/getting-started.adoc b/spring-shell-docs/modules/ROOT/pages/getting-started.adoc
similarity index 92%
rename from spring-shell-docs/src/main/asciidoc/getting-started.adoc
rename to spring-shell-docs/modules/ROOT/pages/getting-started.adoc
index 54049e78a..c0c8b0687 100644
--- a/spring-shell-docs/src/main/asciidoc/getting-started.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/getting-started.adoc
@@ -1,11 +1,14 @@
-== Getting Started
+[[getting-started]]
+= Getting Started
+
To see what Spring Shell has to offer, we can write a trivial _hello world_
shell application that has a simple argument.
IMPORTANT: _Spring Shell_ is based on _Spring Boot_ {spring-boot-version} and
_Spring Framework_ {spring-version} and thus requires _JDK 17_.
-=== Creating a Project
+[[creating-a-project]]
+== Creating a Project
For the purpose of this tutorial, we create a simple Spring Boot application by
using https://start.spring.io where you can choose _Spring Shell_ dependency.
@@ -16,7 +19,6 @@ NOTE: _Spring Shell_ version on `start.spring.io` is usually latest release.
With _maven_ you're expected to have something like:
-====
[source, xml, subs=attributes+]
----
@@ -46,11 +48,9 @@ With _maven_ you're expected to have something like:
----
-====
With _gradle_ you're expected to have something like:
-====
[source, groovy, subs=attributes+]
----
dependencies {
@@ -65,7 +65,6 @@ dependencyManagement {
}
}
----
-====
CAUTION: Given that Spring Shell starts the REPL (Read-Eval-Print-Loop) because this
dependency is present, you need to either skip tests when you build (`-DskipTests`)
@@ -76,27 +75,21 @@ the eval loop or crashes with a NPE.
Once compiled it can be run either in interactive mode:
-====
[source, text, subs=attributes+]
----
-include::code/getting-started-run-interactive.out[]
----
-====
Or in non-interactive mode:
-====
[source, text, subs=attributes+]
----
-include::code/getting-started-run-noninteractive.out[]
----
-====
-TIP: Check out <> making logging to work
+TIP: Check out xref:using-shell-customization-logging.adoc[Logging] making logging to work
better with shell apps.
[[using-spring-shell-your-first-command]]
-=== Your First Command
+== Your First Command
Now we can add our first command. To do so, create a new class (named whatever you want) and
annotate it with `@ShellComponent` which is a variation of `@Component` that is used to restrict
@@ -107,7 +100,6 @@ returns it with "Hello world". Add `@ShellMethod` and optionally change command
using `key` parameter. You can use `@ShellOption` to define argument default value
if it's not given when running a command.
-====
[source, java]
----
package com.example.demo;
@@ -127,21 +119,17 @@ public class MyCommands {
}
}
----
-====
New _hello-world_ command becomes visible to _help_:
-====
[source, text]
----
My Commands
hello-world:
----
-====
And you can run it:
-====
[source, text]
----
shell:>hello-world
@@ -150,6 +138,5 @@ Hello world spring
shell:>hello-world --arg boot
Hello world boot
----
-====
The rest of this document delves deeper into the whole Spring Shell programming model.
diff --git a/spring-shell-docs/modules/ROOT/pages/index.adoc b/spring-shell-docs/modules/ROOT/pages/index.adoc
new file mode 100644
index 000000000..2d44d57f7
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/pages/index.adoc
@@ -0,0 +1,18 @@
+= Spring Shell
+Eric Bottard; Janne Valkealahti; Jay Bryant; Corneil du Plessis
+:page-section-summary-toc: 1
+
+**{project-version}**
+
+Not all applications need a fancy web user interface. Sometimes, interacting with an application through an interactive terminal is the most appropriate way to get things done.
+
+Spring Shell lets you create such a runnable application, where the user enters textual commands that are run until the program terminates. The Spring Shell project provides the infrastructure to create such a REPL (Read, Eval, Print Loop) application, letting you concentrate on implementing commands by using the familiar Spring programming model.
+
+Spring Shell includes advanced features (such as parsing, tab completion, colorization of output, fancy ASCII-art table display, input conversion, and validation), freeing you to focus on core command logic.
+
+(C) 2017 - 2023 VMware, Inc.
+
+_Copies of this document may be made for your own use and for distribution to
+others, provided that you do not charge any fee for such copies and further
+provided that each copy contains this Copyright Notice, whether distributed in
+print or electronically._
\ No newline at end of file
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-basics-reading.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-basics-reading.adoc
similarity index 71%
rename from spring-shell-docs/src/main/asciidoc/using-shell-basics-reading.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-basics-reading.adoc
index b1e089e11..145260450 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-basics-reading.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-basics-reading.adoc
@@ -1,11 +1,12 @@
[[using-shell-basics-reading]]
-=== Reading Docs
+= Reading Docs
+:page-section-summary-toc: 1
Throughout this documentation, we make references to configuring something by using
annotations or programmatic examples.
-NOTE: There are two annotation models, <>
-referred to new annotation model, <>
+NOTE: There are two annotation models, xref:using-shell-commands-registration-annotation.adoc[annotations]
+referred to new annotation model, xref:using-shell-commands-registration-legacyannotation.adoc[legacy annotations]
referred to old legacy annotation model.
Old legacy annotation model mostly relates to use of `@ShellMethod` and `@ShellOption` and
@@ -15,4 +16,4 @@ The programmatic model is how things are actually registered, even if you use an
NOTE: Currently whole documentation structure is in transit to provide better
structure how things can be used using different ways to provide configurations.
-So pardon a for little confusion now and there during a transit.
\ No newline at end of file
+So pardon a for little confusion now and there during a transit.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-basics.adoc
similarity index 92%
rename from spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-basics.adoc
index 39c83693a..c54c90a25 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-basics.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-basics.adoc
@@ -1,5 +1,7 @@
[[using-shell-basics]]
-== Basics
+= Basics
+:page-section-summary-toc: 1
+
This section covers the basics of Spring Shell. Before going on to define actual commands and options,
we need to go through some of the fundamental concepts of Spring Shell.
@@ -13,4 +15,3 @@ Essentially, a few things needs to happen before you have a working Spring Shell
You can get a full working Spring Shell application without defining any user-level commands
as some basic built-in commands (such as `help` and `history`) are provided.
-include::using-shell-basics-reading.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-building.adoc
similarity index 97%
rename from spring-shell-docs/src/main/asciidoc/using-shell-building.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-building.adoc
index 0077819d0..88327727c 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-building.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-building.adoc
@@ -1,10 +1,10 @@
[[using-shell-building]]
-== Building
+= Building
This section covers how to build a Spring Shell application.
[[native]]
-=== Native Support
+== Native Support
Support for compiling _Spring Shell_ application into a _GraalVM_ binary
mostly comes from _Spring Framework_ and _Spring Boot_ where feature is
@@ -23,7 +23,6 @@ _GraalVM_ installed and `JAVA_HOME` pointing to that.
For _gradle_ add graalvm's native plugin and configure metadata repository.
-====
[source, groovy, subs=attributes+]
----
plugins {
@@ -36,7 +35,6 @@ graalvmNative {
}
}
----
-====
When gradle build is run with `./gradlew nativeCompile` you should get binary
under `build/native/nativeCompile` directory.
@@ -44,7 +42,6 @@ under `build/native/nativeCompile` directory.
For `maven` use `spring-boot-starter-parent` as parent and you'll get `native`
profile which can be used to do a compilation. You need to configure metadata repository
-====
[source, xml, subs=attributes+]
----
@@ -63,7 +60,6 @@ profile which can be used to do a compilation. You need to configure metadata re
----
-====
NOTE: If you rely on `spring-boot-starter-parent` it manages `native-maven-plugin`
version which is kept up to date.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-availability.adoc
similarity index 97%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-availability.adoc
index 95d537215..7da32cdd4 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-availability.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-availability.adoc
@@ -1,5 +1,5 @@
[[dynamic-command-availability]]
-=== Dynamic Command Availability
+= Dynamic Command Availability
Registered commands do not always make sense, due to the internal state of the application.
For example, there may be a `download` command, but it only works once the user has used `connect` on a remote
@@ -12,7 +12,6 @@ There are three possible ways for a command to indicate availability.
They all use a no-arg method that returns an instance of `Availability`.
Consider the following example:
-====
[source, java]
----
@ShellComponent
@@ -38,7 +37,6 @@ public class MyCommands {
}
}
----
-====
The `connect` method is used to connect to the server (details omitted), altering the state
of the command through the `connected` boolean when done.
@@ -48,16 +46,14 @@ The method returns an instance of `Availability`, constructed with one of the tw
If the command is not available, an explanation has to be provided.
Now, if the user tries to invoke the command while not being connected, here is what happens:
-====
[source]
----
shell:>download
Command 'download' exists but is not currently available because you are not connected.
Details of the error have been omitted. You can use the stacktrace command to print the full stacktrace.
----
-====
-Information about currently unavailable commands is also used in the integrated help. See <>.
+Information about currently unavailable commands is also used in the integrated help. See xref:using-shell-commands-builtin-help.adoc[Help].
[TIP]
====
@@ -69,7 +65,6 @@ You should not start the sentence with a capital or add a final period
If naming the availability method after the name of the command method does not suit you, you
can provide an explicit name by using the `@ShellMethodAvailability` annotation:
-====
[source, java]
----
@ShellMethod("Download the nuclear codes.")
@@ -85,14 +80,12 @@ can provide an explicit name by using the `@ShellMethodAvailability` annotation:
}
----
<1> the names have to match
-====
Finally, it is often the case that several commands in the same class share the same internal state and, thus,
should all be available or unavailable as a group. Instead of having to stick the `@ShellMethodAvailability`
on all command methods, Spring Shell lets you flip things around and put the `@ShellMethodAvailabilty`
annotation on the availability method, specifying the names of the commands that it controls:
-====
[source, java]
----
@ShellMethod("Download the nuclear codes.")
@@ -112,7 +105,6 @@ annotation on the availability method, specifying the names of the commands that
: Availability.unavailable("you are not connected");
}
----
-====
[TIP]
=====
@@ -120,7 +112,6 @@ The default value for the `@ShellMethodAvailability.value()` attribute is `*`. T
wildcard matches all command names. This makes it easy to turn all commands of a single class on or off
with a single availability method:
-====
[source,java]
----
@ShellComponent
@@ -139,7 +130,6 @@ public class Toggles {
public void bar() {}
}
----
-====
=====
TIP: Spring Shell does not impose many constraints on how to write commands and how to organize classes.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-clear.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-clear.adoc
similarity index 79%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-clear.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-clear.adoc
index f335f39fb..0d36f1bd5 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-clear.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-clear.adoc
@@ -1,4 +1,6 @@
[[built-in-commands-clear]]
-==== Clear
+= Clear
+:page-section-summary-toc: 1
+
The `clear` command does what you would expect and clears the screen, resetting the prompt
in the top left corner.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-completion.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-completion.adoc
similarity index 88%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-completion.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-completion.adoc
index e933aefe1..1e69a1293 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-completion.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-completion.adoc
@@ -1,5 +1,6 @@
[[built-in-commands-completion]]
-==== Completion
+= Completion
+:page-section-summary-toc: 1
The `completion` command set lets you create script files that can be used
with am OS shell implementations to provide completion. This is very useful when
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-exit.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-exit.adoc
similarity index 88%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-exit.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-exit.adoc
index bb380f374..5f8e05c2b 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-exit.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-exit.adoc
@@ -1,5 +1,6 @@
[[built-in-commands-exit]]
-==== Exit
+= Exit
+:page-section-summary-toc: 1
The `quit` command (also aliased as `exit`) requests the shell to quit, gracefully
closing the Spring application context. If not overridden, a JLine `History` bean writes a history of all
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-help.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-help.adoc
similarity index 86%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-help.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-help.adoc
index 162234abd..7b6735a9f 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-help.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-help.adoc
@@ -1,5 +1,5 @@
[[built-in-commands-help]]
-==== Help
+= Help
Running a shell application often implies that the user is in a graphically limited
environment. Also, while we are nearly always connected in the era of mobile phones,
@@ -7,10 +7,9 @@ accessing a web browser or any other rich UI application (such as a PDF viewer)
be possible. This is why it is important that the shell commands are correctly self-documented, and this is where the `help`
command comes in.
-Typing `help` + `ENTER` lists all the commands known to the shell (including <> commands)
+Typing `help` + `ENTER` lists all the commands known to the shell (including xref:using-shell-commands-availability.adoc[unavailable] commands)
and a short description of what they do, similar to the following:
-====
[source, bash]
----
my-shell:>help
@@ -27,14 +26,12 @@ Built-In Commands
version: Show version info
script: Read and execute commands from a file.
----
-====
Typing `help ` shows more detailed information about a command, including the available parameters, their
type, whether they are mandatory or not, and other details.
The following listing shows the `help` command applied to itself:
-====
[source, bash]
----
my-shell:>help help
@@ -49,7 +46,6 @@ OPTIONS
The command to obtain help for.
[Optional]
----
-====
Help is templated and can be customized if needed. Settings are under `spring.shell.command.help` where you can use
`enabled` to disable command, `grouping-mode` taking `group` or `flat` if you want to hide groups by flattening
@@ -58,7 +54,6 @@ output of a command list.
If `spring.shell.command.help.grouping-mode=flat` is set, then help would show:
-====
[source, bash]
----
my-shell:>help help
@@ -74,7 +69,6 @@ completion bash: Generate bash completion script
version: Show version info
script: Read and execute commands from a file.
----
-====
Output from `help` and `help ` are both templated with a default implementation
which can be changed.
@@ -96,10 +90,10 @@ as a model.
|`true` if showing groups is enabled. Otherwise, false.
|`groups`
-|The commands variables (see <>).
+|The commands variables (see xref:using-shell-commands-builtin-help.adoc#groupcommandinfomodel-variables[GroupCommandInfoModel Variables]).
|`commands`
-|The commands variables (see <>).
+|The commands variables (see xref:using-shell-commands-builtin-help.adoc#commandinfomodel-variables[CommandInfoModel Variables]).
|`hasUnavailableCommands`
|`true` if there is unavailable commands. Otherwise, false.
@@ -114,7 +108,7 @@ as a model.
|The name of a group, if set. Otherwise, empty.
|`commands`
-|The commands, if set. Otherwise, empty. Type is a multi value, see <>.
+|The commands, if set. Otherwise, empty. Type is a multi value, see xref:using-shell-commands-builtin-help.adoc#commandinfomodel-variables[CommandInfoModel Variables].
|===
[[commandinfomodel-variables]]
@@ -135,10 +129,10 @@ as a model.
|The description of a command, if set. Otherwise, null.
|`parameters`
-|The parameters variables, if set. Otherwise empty. Type is a multi value, see <>.
+|The parameters variables, if set. Otherwise empty. Type is a multi value, see xref:using-shell-commands-builtin-help.adoc#commandparameterinfomodel-variables[CommandParameterInfoModel Variables].
|`availability`
-|The availability variables (see <>).
+|The availability variables (see xref:using-shell-commands-builtin-help.adoc#commandavailabilityinfomodel-variables[CommandAvailabilityInfoModel Variables]).
|===
[[commandparameterinfomodel-variables]]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-history.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-history.adoc
similarity index 85%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-history.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-history.adoc
index 0e79d5cff..d3e8210b2 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-history.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-history.adoc
@@ -1,5 +1,6 @@
[[built-in-commands-history]]
-==== History
+= History
+:page-section-summary-toc: 1
The `history` command shows the history of commands that has been executed.
@@ -11,6 +12,6 @@ which you can change by setting `spring.shell.history.name`.
By default, a log file is generated to a current working directory, which you can dictate
by setting `spring.shell.config.location`. This property can contain
-a placeholder (`{userconfig}`), which resolves to a common shared config directory.
+a placeholder (`+{userconfig}+`), which resolves to a common shared config directory.
TIP: Run the Spring Shell application to see how the sample application works as it uses these options.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-script.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-script.adoc
similarity index 89%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-script.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-script.adoc
index b87416af4..2afe28fad 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-script.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-script.adoc
@@ -1,5 +1,6 @@
[[built-in-commands-script]]
-==== Script
+= Script
+:page-section-summary-toc: 1
The `script` command accepts a local file as an argument and replays commands found there, one at a time.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-stacktrace.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-stacktrace.adoc
similarity index 92%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-stacktrace.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-stacktrace.adoc
index ba9684ba0..f3183012a 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-stacktrace.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-stacktrace.adoc
@@ -1,5 +1,6 @@
[[built-in-commands-stacktrace]]
-==== Stacktrace
+= Stacktrace
+:page-section-summary-toc: 1
When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed
so as not to overflow the user with too much information.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-version.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-version.adoc
similarity index 97%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-version.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-version.adoc
index dc8339e62..6d54e161f 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin-version.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin-version.adoc
@@ -1,5 +1,5 @@
[[built-in-commands-version]]
-==== Version
+= Version
The `version` command shows existing build and git info by integrating into
Boot's `BuildProperties` and `GitProperties` if those exist in the shell application.
@@ -16,21 +16,17 @@ fields in a default template.
The template defaults to `classpath:template/version-default.st`, and you can define
your own, as the following example shows:
-====
[source]
----
----
-====
This setting would output something like the following:
-====
[source]
----
X.X.X
----
-====
You can add the following attributes to the default template rendering: `buildVersion`, `buildGroup`,
`buildGroup`, `buildName`, `buildTime`, `gitShortCommitId`, `gitCommitId`,
diff --git a/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin.adoc
new file mode 100644
index 000000000..521eb5ee7
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-builtin.adoc
@@ -0,0 +1,11 @@
+[[built-in-commands]]
+= Built-In Commands
+:page-section-summary-toc: 1
+
+
+
+
+
+
+
+
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-annotation.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-annotation.adoc
similarity index 96%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-annotation.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-annotation.adoc
index e20a51e4d..76d28871e 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-annotation.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-annotation.adoc
@@ -1,5 +1,6 @@
[[dynamic-command-exitcode-annotation]]
-==== @ExceptionResolver
+= @ExceptionResolver
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
`@ShellComponent` classes can have `@ExceptionResolver` methods to handle exceptions from component
@@ -17,42 +18,35 @@ is used to sort exceptions based on their depth from the thrown exception type.
Alternatively, the annotation declaration may narrow the exception types to match, as the
following example shows:
-====
[source, java, indent=0]
----
include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-type-in-annotation]
----
-====
-====
[source, java, indent=0]
----
include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-type-in-method]
----
-====
`@ExceptionResolver` can also return `String` which is used as an output to console. You can
use `@ExitCode` annotation to define return code.
-====
[source, java, indent=0]
----
include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-exitcode-annotation]
----
-====
`@ExceptionResolver` with `void` return type is automatically handled as handled exception.
You can then also define `@ExitCode` and use `Terminal` if you need to write something
into console.
-====
[source, java, indent=0]
----
include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-void]
----
-====
-===== Method Arguments
+[[method-arguments]]
+== Method Arguments
`@ExceptionResolver` methods support the following arguments:
[Attributes]
@@ -67,7 +61,8 @@ include::{snippets}/ErrorHandlingSnippets.java[tag=exception-resolver-with-void]
|===
-===== Return Values
+[[return-values]]
+== Return Values
`@ExceptionResolver` methods support the following return values:
[Attributes]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-mappings.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-mappings.adoc
similarity index 96%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-mappings.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-mappings.adoc
index 951e9f2b6..b83f91fce 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-mappings.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-mappings.adoc
@@ -1,5 +1,6 @@
[[dynamic-command-exitcode-mappings]]
-==== Exit Code Mappings
+= Exit Code Mappings
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Default behaviour of an exit codes is as:
@@ -14,21 +15,17 @@ integrate into that.
Assuming there is an exception show below which would be thrown from a command:
-====
[source, java, indent=0]
----
include::{snippets}/ExitCodeSnippets.java[tag=my-exception-class]
----
-====
It is possible to define a mapping function between `Throwable` and exit code. You can also
just configure a _class_ to _exit code_ which is just a syntactic sugar within configurations.
-====
[source, java, indent=0]
----
include::{snippets}/ExitCodeSnippets.java[tag=example1]
----
-====
NOTE: Exit codes cannot be customized with annotation based configuration
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-resolving.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-resolving.adoc
similarity index 96%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-resolving.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-resolving.adoc
index eb4998bb9..778d96a26 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling-resolving.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling-resolving.adoc
@@ -1,5 +1,6 @@
[[dynamic-command-exitcode-resolving]]
-==== Exception Resolving
+= Exception Resolving
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Unhandled exceptions will bubble up into shell's `ResultHandlerService` and then eventually
@@ -8,30 +9,24 @@ can be used to resolve exceptions and gives you flexibility to return message to
into console together with exit code which are wrapped within `CommandHandlingResult`.
`CommandHandlingResult` may contain a _message_ and/or _exit code_.
-====
[source, java, indent=0]
----
include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-resolver-class]
----
-====
`CommandExceptionResolver` implementations can be defined globally as bean.
-====
[source, java, indent=0]
----
include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-resolver-class-as-bean]
----
-====
or defined per `CommandRegistration` if it's applicable only for a particular command itself.
-====
[source, java, indent=0]
----
include::{snippets}/ErrorHandlingSnippets.java[tag=example1]
----
-====
NOTE: Resolvers defined with a command are handled before global resolvers.
@@ -39,12 +34,10 @@ NOTE: Resolvers defined with a command are handled before global resolvers.
Use you own exception types which can also be an instance of boot's `ExitCodeGenerator` if
you want to define exit code there.
-====
[source, java, indent=0]
----
include::{snippets}/ErrorHandlingSnippets.java[tag=my-exception-class]
----
-====
Some build in `CommandExceptionResolver` beans are registered to handle common
exceptions thrown from command parsing. These are registered with _order_
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling.adoc
similarity index 76%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling.adoc
index 60b7b867d..041ba897c 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-exceptionhandling.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-exceptionhandling.adoc
@@ -1,5 +1,7 @@
[[dynamic-command-exitcode]]
-=== Exception Handling
+= Exception Handling
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Exceptions happen from a user code wether it is intentional or not. This section describes
@@ -12,8 +14,5 @@ this mostly relates when a command is run on a non-interactive mode meaning one
is always executed once with an instance of a `spring-shell`. Take a note that _exit code_
always relates to non-interactive shell.
-include::using-shell-commands-exceptionhandling-resolving.adoc[]
-include::using-shell-commands-exceptionhandling-mappings.adoc[]
-include::using-shell-commands-exceptionhandling-annotation.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-helpoptions.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-helpoptions.adoc
similarity index 97%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-helpoptions.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-helpoptions.adoc
index a34187826..6c686eefe 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-helpoptions.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-helpoptions.adoc
@@ -1,5 +1,6 @@
[[commands-helpoptions]]
-=== Help Options
+= Help Options
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
_Spring Shell_ has a build-in `help` command but not all favour getting command help
@@ -14,16 +15,13 @@ what other command-line options is typed.
Below example shows its default settings.
-====
[source, java, indent=0]
----
include::{snippets}/CommandRegistrationHelpOptionsSnippets.java[tag=defaults]
----
-====
It is possible to change default behaviour via configuration options.
-====
[source, yaml]
----
spring:
@@ -34,7 +32,6 @@ spring:
short-names: h
command: help
----
-====
NOTE: Commands defined programmationally or via annotations will automatically add
help options. With annotation model you can only turn things off globally, programmatic
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-hidden.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-hidden.adoc
similarity index 96%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-hidden.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-hidden.adoc
index f0a75950a..7014c8b53 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-hidden.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-hidden.adoc
@@ -1,5 +1,6 @@
[[commands-hidden]]
-=== Hidden Command
+= Hidden Command
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
It is possible to _hide_ a command which is convenient in cases where it is not yet ready for
@@ -17,11 +18,9 @@ from:
Below is an example how to define command as _hidden_. It shows available builder methods
to define _hidden_ state.
-====
[source, java, indent=0]
----
include::{snippets}/CommandRegistrationHiddenSnippets.java[tag=snippet1]
----
-====
NOTE: Defining hidden commands is not supported with annotation based configuration
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-interactionmode.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-interactionmode.adoc
similarity index 71%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-interactionmode.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-interactionmode.adoc
index fd3d7fd5a..11a42107e 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-interactionmode.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-interactionmode.adoc
@@ -1,24 +1,22 @@
[[commands-interactionmode]]
-=== Interaction Mode
+= Interaction Mode
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Command registration can define `InteractionMode` which is used to hide commands
-depending which mode shell is executing. More about that in <>.
+depending which mode shell is executing. More about that in xref:using-shell-execution.adoc#using-shell-execution-interactionmode[Interaction Mode].
You can define it with `CommandRegisration`.
-====
[source, java, indent=0]
----
include::{snippets}/CommandRegistrationInteractionModeSnippets.java[tag=snippet1]
----
-====
Or with `@ShellMethod`.
-====
[source, java, indent=0]
----
include::{snippets}/CommandRegistrationInteractionModeSnippets.java[tag=snippet2]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-organize.adoc
similarity index 98%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-organize.adoc
index 1f4041af6..8a275adb7 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-organize.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-organize.adoc
@@ -1,5 +1,5 @@
[[organizing-commands]]
-=== Organizing Commands
+= Organizing Commands
When your shell starts to provide a lot of functionality, you may end up
with a lot of commands, which could be confusing for your users. By typing `help`,
@@ -27,7 +27,6 @@ package (unless overridden at the method or class level, as explained earlier).
The following listing shows an example:
-====
[source,java]
----
public class UserCommands {
@@ -51,4 +50,3 @@ public class SomeCommands {
public void last() {}
}
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration-annotation.adoc
similarity index 96%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration-annotation.adoc
index e8772b00a..3d5e8b667 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-annotation.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration-annotation.adoc
@@ -1,27 +1,24 @@
[[commands-registration-annotation]]
-==== Annotation
+= Annotation
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
`@Command` annotation when used on a method marks it as a candidate for command registration.
In below example a command `example` is defined.
-====
[source, java, indent=0]
----
include::{snippets}/CommandAnnotationSnippets.java[tag=command-anno-in-method]
----
-====
`@Command` annotation can be placed on a class which either defines defaults or shared settings
for `@Command` methods defined in a same class. In below example a command `parent example` is
defined.
-====
[source, java, indent=0]
----
include::{snippets}/CommandAnnotationSnippets.java[tag=command-anno-in-class]
----
-====
Using a `@Command` will not automatically register command targets, instead it is required to use
`@EnableCommand` and/or `@CommandScan` annotations. This model is familiar from other parts
@@ -31,12 +28,10 @@ for command targets.
You can define target classes using `@EnableCommand`. It will get picked from all _Configuration_
classes.
-====
[source, java, indent=0]
----
include::{snippets}/CommandAnnotationSnippets.java[tag=enablecommand-with-class]
----
-====
You can define target classes using `@CommandScan`. It will get picked from all _Configuration_
classes.
@@ -44,9 +39,7 @@ classes.
TIP: Define `@CommandScan` in Spring Boot `App` class on a top level and it will automatically
scan all command targets from all packages and classes under `App`.
-====
[source, java, indent=0]
----
include::{snippets}/CommandAnnotationSnippets.java[tag=commandscan-no-args]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration-legacyannotation.adoc
similarity index 96%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration-legacyannotation.adoc
index cded09073..b146984a3 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-legacyannotation.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration-legacyannotation.adoc
@@ -1,5 +1,6 @@
[[commands-registration-legacyannotation]]
-==== Legacy Annotation
+= Legacy Annotation
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
When you use the standard API, methods on beans are turned into executable commands, provided that:
@@ -16,16 +17,14 @@ you can use it in addition to the filtering mechanism to declare beans (for exam
You can customize the name of the created bean by using the `value` attribute of the annotation.
====
-====
[source, java, indent=0]
----
include::{snippets}/AnnotationRegistrationSnippets.java[tag=snippet1]
----
-====
The only required attribute of the `@ShellMethod` annotation is its `value` attribute, which should have
a short, one-sentence, description of what the command does. This lets your users
-get consistent help about your commands without having to leave the shell (see <>).
+get consistent help about your commands without having to leave the shell (see xref:using-shell-commands-builtin-help.adoc[Help]).
NOTE: The description of your command should be short -- no more than one or two sentences. For better
consistency, it should start with a capital letter and end with a period.
@@ -36,12 +35,10 @@ dashed, gnu-style, names (for example, `sayHello()` becomes `say-hello`).
You can, however, explicitly set the command key, by using the `key` attribute of the annotation:
-====
[source, java, indent=0]
----
include::{snippets}/AnnotationRegistrationSnippets.java[tag=snippet2]
----
-====
NOTE: The `key` attribute accepts multiple values.
If you set multiple keys for a single method, the command is registered with those different aliases.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration-programmatic.adoc
similarity index 91%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration-programmatic.adoc
index ad7b8a2a7..1e9488955 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration-programmatic.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration-programmatic.adoc
@@ -1,16 +1,15 @@
[[commands-registration-programmatic]]
-==== Programmatic
+= Programmatic
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
In the programmatic model, `CommandRegistration` can be defined as a `@Bean`
and it will be automatically registered.
-====
[source, java, indent=0]
----
include::{snippets}/CommandRegistrationBeanSnippets.java[tag=plain]
----
-====
If all your commands have something in common, an instance of
a _CommandRegistration.BuilderSupplier_ is created which can
@@ -18,24 +17,20 @@ be autowired. Default implementation of this supplier returns
a new builder so you don't need to worry about its internal state.
IMPORTANT: Commands registered programmatically automatically
-add _help options_ mentioned in <>.
+add _help options_ mentioned in xref:using-shell-commands-helpoptions.adoc[Help Options].
If bean of this supplier type is defined then auto-configuration
will back off giving you an option to redefine default functionality.
-====
[source, java, indent=0]
----
include::{snippets}/CommandRegistrationBeanSnippets.java[tag=fromsupplier]
----
-====
`CommandRegistrationCustomizer` beans can be defined if you want to centrally
modify builder instance given you by supplier mentioned above.
-====
[source, java, indent=0]
----
include::{snippets}/CommandRegistrationBeanSnippets.java[tag=customizer]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration.adoc
similarity index 65%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration.adoc
index b90610761..9efd25b06 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-registration.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-registration.adoc
@@ -1,4 +1,7 @@
-=== Registration
+[[registration]]
+= Registration
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
There are two different ways to define a command: through an annotation model and
@@ -8,14 +11,11 @@ In the programmatic model, you use a more low level approach, defining command
registrations (either as beans or by dynamically registering with a command catalog).
Starting from _3.1.x_ a better support for defining commands using
-<> were added. Firstly because eventually standard
-package providing <> will get deprecated
+xref:using-shell-commands-registration-annotation.adoc[annotations] were added. Firstly because eventually standard
+package providing xref:using-shell-commands-registration-legacyannotation.adoc[legacy annotations] will get deprecated
and removed. Secondly so that we're able to provide same set of features than using underlying
`CommandRegistration`. Creating new a annotation model allows us to rethink and modernise that
part without breaking existing applications.
-include::using-shell-commands-registration-programmatic.adoc[]
-include::using-shell-commands-registration-annotation.adoc[]
-include::using-shell-commands-registration-legacyannotation.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-writing.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-writing.adoc
similarity index 95%
rename from spring-shell-docs/src/main/asciidoc/using-shell-commands-writing.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-commands-writing.adoc
index 7f73f25b9..e19ae3115 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-writing.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands-writing.adoc
@@ -1,4 +1,6 @@
-=== Writing
+[[writing]]
+= Writing
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
When something needs to get written into your console you can always
@@ -10,18 +12,14 @@ If using target endpoints, i.e. _consumer_ which is not expected
to return anything given `CommandContext` contains reference to
`Terminal` and writer can be accessed from there.
-====
[source, java, indent=0]
----
include::{snippets}/WritingSnippets.java[tag=reg-terminal-writer]
----
-====
It's possible to autowire `Terminal` to get access to its writer.
-====
[source, java, indent=0]
----
include::{snippets}/WritingSnippets.java[tag=anno-terminal-writer]
----
-====
diff --git a/spring-shell-docs/modules/ROOT/pages/using-shell-commands.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-commands.adoc
new file mode 100644
index 000000000..663af4184
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-commands.adoc
@@ -0,0 +1,18 @@
+[[commands]]
+= Commands
+:page-section-summary-toc: 1
+
+ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
+
+In this section, we go through an actual command registration and leave command options
+and execution for later in a documentation. You can find more detailed info in
+xref:appendices-techical-intro-registration.adoc[Command Registration].
+
+
+
+
+
+
+
+
+
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-completion.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-completion.adoc
similarity index 90%
rename from spring-shell-docs/src/main/asciidoc/using-shell-completion.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-completion.adoc
index d53907c03..8d0d41670 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-completion.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-completion.adoc
@@ -1,4 +1,6 @@
-== Completion
+[[completion]]
+= Completion
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Spring Shell can provide completion proposals for both interactive shell
@@ -8,7 +10,8 @@ easier to provide more programmatic ways to provide completion hints.
When shell is purely run as a command-line tool a completion can only
be accomplished with integration into OS level shell's like _bash_.
-=== Interactive
+[[interactive]]
+== Interactive
Hints for completions are calculated with _function_ or _interface_ style
methods which takes `CompletionContext` and returns a list of
@@ -20,45 +23,38 @@ for all commands and scenarious. For example existing completion
implementation `RegistrationOptionsCompletionResolver` handles completions
for a option names.
-====
[source, java, indent=0]
----
include::{snippets}/CompletionSnippets.java[tag=resolver-1]
----
-====
Option values with builder based command registration can be
defined per option.
-====
[source, java, indent=0]
----
include::{snippets}/CompletionSnippets.java[tag=builder-1]
----
-====
Option values with annotation based command registration are handled
via `ValueProvider` interface which can be defined with `@ShellOption`
annotation.
-====
[source, java, indent=0]
----
include::{snippets}/CompletionSnippets.java[tag=provider-1]
----
-====
Actual `ValueProvider` with annotation based command needs to be
registered as a _Bean_.
-====
[source, java, indent=0]
----
include::{snippets}/CompletionSnippets.java[tag=anno-method]
----
-====
-=== Command-Line
+[[command-line]]
+== Command-Line
Command-line completion currently only support _bash_ and is documented
-in a built-in `completion` command <>.
+in a built-in `completion` command xref:using-shell-commands-builtin-completion.adoc[Completion].
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components-flow.adoc
similarity index 81%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components-flow.adoc
index 5faf17649..d7f03e913 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-flow.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components-flow.adoc
@@ -1,8 +1,9 @@
[[using-shell-components-flow]]
-=== Flow
+= Flow
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
-When you use <> to build something that involves
+When you use xref:using-shell-components-ui.adoc[Flow Components] to build something that involves
use of a multiple components, your implementation may become a bit cluttered.
To ease these use cases, we added a
`ComponentFlow` that can hook multiple component executions together
@@ -10,28 +11,24 @@ as a "`flow`".
The following listings show examples of flows and their output in a shell:
-====
[source, java, indent=0]
----
include::{snippets}/FlowComponentSnippets.java[tag=snippet1]
----
-====
-image::images/component-flow-showcase-1.svg[text input]
+image::component-flow-showcase-1.svg[text input]
Normal execution order of a components is same as defined with a builder. It's
possible to conditionally choose where to jump in a flow by using a `next`
function and returning target _component id_. If this returned id is aither _null_
or doesn't exist flow is essentially stopped right there.
-====
[source, java, indent=0]
----
include::{snippets}/FlowComponentSnippets.java[tag=snippet2]
----
-====
-image::images/component-flow-conditional-1.svg[text input]
+image::component-flow-conditional-1.svg[text input]
TIP: The result from running a flow returns `ComponentFlowResult`, which you can
use to do further actions.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-confirmation.adoc
similarity index 75%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-confirmation.adoc
index 4046895c6..c7bf861cd 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-confirmation.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-confirmation.adoc
@@ -1,20 +1,19 @@
[[using-shell-components-ui-confirmation]]
-==== Confirmation
+= Confirmation
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
The confirmation component asks a user for a simple confirmation. It is essentially a
yes-or-no question.
-====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet5]
----
-====
The following image shows the typical output from a confirmation component:
-image::images/component-confirmation-1.svg[text input]
+image::component-confirmation-1.svg[text input]
The context object is `ConfirmationInputContext`. The following table describes its context variables:
@@ -27,5 +26,5 @@ The context object is `ConfirmationInputContext`. The following table describes
|The default value -- either `true` or `false`.
|`model`
-|The parent context variables (see <>).
+|The parent context variables (see xref:using-shell-components-ui-render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]).
|===
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-multiselect.adoc
similarity index 77%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-multiselect.adoc
index b59d9540d..4ba79df2f 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-multiselect.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-multiselect.adoc
@@ -1,20 +1,19 @@
[[using-shell-components-ui-multiselect]]
-==== Multi Select
+= Multi Select
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
The multi select component asks a user to select multiple items from a list.
The following listing shows an example:
-====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet7]
----
-====
The following image shows a typical multi-select component:
-image::images/component-multi-select-1.svg[text input]
+image::component-multi-select-1.svg[text input]
The context object is `MultiItemSelectorContext`. The following table describes its context variables:
@@ -30,5 +29,5 @@ The context object is `MultiItemSelectorContext`. The following table describes
|The visible items, where rows contain maps of name, selected, on-row, and enabled items.
|`model`
-|The parent context variables (see <>).
+|The parent context variables (see xref:using-shell-components-ui-render.adoc#selectorcomponentcontext-template-variables[SelectorComponentContext Template Variables]).
|===
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-pathinput.adoc
similarity index 73%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-pathinput.adoc
index 76cb6f23c..1c9772e3c 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathinput.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-pathinput.adoc
@@ -1,19 +1,18 @@
[[using-shell-components-ui-pathinput]]
-==== Path Input
+= Path Input
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
The path input component asks a user for a `Path` and gives additional information about a path itself.
-====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet4]
----
-====
The following image shows typical output from a path input component:
-image::images/component-path-input-1.svg[text input]
+image::component-path-input-1.svg[text input]
The context object is `PathInputContext`. The following table describes its context variables:
@@ -23,5 +22,5 @@ The context object is `PathInputContext`. The following table describes its cont
|Key |Description
|`model`
-|The parent context variables (see <>).
+|The parent context variables (see xref:using-shell-components-ui-render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]).
|===
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-pathsearch.adoc
similarity index 74%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-pathsearch.adoc
index aaf1b9a5f..886acd36d 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-pathsearch.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-pathsearch.adoc
@@ -1,24 +1,23 @@
[[using-shell-components-ui-pathsearch]]
-==== Path Search
+= Path Search
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
The path search component asks base directory for scan and optional search expression.
Results are shown in a single select list where user can pick a path.
`PathSearchConfig` can be used to customise component behaviour.
-====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet9]
----
-====
NOTE: Logic for search is passed as is into algorithms documented
-in <>.
+in xref:appendices-techical-intro-searchalgorithm.adoc[Search Algorithms].
The following image shows typical output from a path search component:
-image::images/component-path-search-1.svg[text input]
+image::component-path-search-1.svg[text input]
The context object is `PathSearchContext`. The following table describes its context variables:
@@ -31,5 +30,5 @@ The context object is `PathSearchContext`. The following table describes its con
|The items available for rendering search results.
|`model`
-|The parent context variables (see <>).
+|The parent context variables (see xref:using-shell-components-ui-render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]).
|===
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-render.adoc
similarity index 98%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-render.adoc
index 5b7e2390e..8e6ebc970 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-render.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-render.adoc
@@ -1,5 +1,6 @@
[[using-shell-components-ui-render]]
-==== Component Render
+= Component Render
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
You can implement component rendering in either of two ways: fully
@@ -14,21 +15,17 @@ through code then gives you flexibility to do whatever you need.
The programmatic way to render is to create a `Function`:
-====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet1]
----
-====
Then you can hook it to a component:
-====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet2]
----
-====
Components have their own context but usually share some functionality
from a parent component types. The following tables show those context variables:
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-singleselect.adoc
similarity index 82%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-singleselect.adoc
index 78aba16ef..993c4e4c3 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-singleselect.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-singleselect.adoc
@@ -1,20 +1,19 @@
[[using-shell-components-ui-singleselect]]
-==== Single Select
+= Single Select
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
A single select component asks a user to choose one item from a list. It is similar to a simple
dropbox implementation. The following listing shows an example:
-====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet6]
----
-====
The following image shows typical output for a single select component:
-image::images/component-single-select-1.svg[text input]
+image::component-single-select-1.svg[text input]
The context object is `SingleItemSelectorContext`. The following table describes its context variables:
@@ -30,16 +29,14 @@ The context object is `SingleItemSelectorContext`. The following table describes
|The visible items, where rows contains maps of name and selected items.
|`model`
-|The parent context variables (see <>).
+|The parent context variables (see xref:using-shell-components-ui-render.adoc#selectorcomponentcontext-template-variables[SelectorComponentContext Template Variables]).
|===
You can pre-select an item by defining it to get exposed. This is
useful if you know the default and lets the user merely press `Enter` to make a choice.
The following listing sets a default:
-====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet8]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-stringinput.adoc
similarity index 81%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-stringinput.adoc
index b88574a64..d2130a340 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui-stringinput.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui-stringinput.adoc
@@ -1,20 +1,19 @@
[[using-shell-components-ui-stringinput]]
-==== String Input
+= String Input
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
The string input component asks a user for simple text input, optionally masking values
if the content contains something sensitive. The following listing shows an example:
-====
[source, java, indent=0]
----
include::{snippets}/UiComponentSnippets.java[tag=snippet3]
----
-====
The following image shows typical output from a string input component:
-image::images/component-text-input-1.svg[text input]
+image::component-text-input-1.svg[text input]
The context object is `StringInputContext`. The following table lists its context variables:
@@ -39,5 +38,5 @@ The context object is `StringInputContext`. The following table lists its contex
|`true` if a mask character is set. Otherwise, false.
|`model`
-|The parent context variables (see <>).
+|The parent context variables (see xref:using-shell-components-ui-render.adoc#textcomponentcontext-template-variables[TextComponentContext Template Variables]).
|===
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui.adoc
similarity index 61%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components-ui.adoc
index a2a08a1fb..dddb73011 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components-ui.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components-ui.adoc
@@ -1,5 +1,6 @@
[[using-shell-components-ui]]
-=== Flow Components
+= Flow Components
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Starting from version 2.1.x, a new component model provides an
@@ -18,19 +19,12 @@ Built-in components generally follow this logic:
. Exit.
. Render the final status of a component state.
-NOTE: <> gives better interface for defining the flow of
+NOTE: xref:using-shell-components-flow.adoc[Flow] gives better interface for defining the flow of
components that are better suited for defining interactive command flows.
-include::using-shell-components-ui-render.adoc[]
-include::using-shell-components-ui-stringinput.adoc[]
-include::using-shell-components-ui-pathinput.adoc[]
-include::using-shell-components-ui-pathsearch.adoc[]
-include::using-shell-components-ui-confirmation.adoc[]
-include::using-shell-components-ui-singleselect.adoc[]
-include::using-shell-components-ui-multiselect.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-components.adoc
similarity index 73%
rename from spring-shell-docs/src/main/asciidoc/using-shell-components.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-components.adoc
index 7a31c5df4..dcbec06b0 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-components.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-components.adoc
@@ -1,11 +1,10 @@
[[using-shell-components]]
-== Components
+= Components
+:page-section-summary-toc: 1
Components are a set of features which are either build-in or something
you can re-use or extend for your own needs. Components in question are
either built-in _commands_ or UI side components providing higher level
features within commands itself.
-include::using-shell-components-flow.adoc[]
-include::using-shell-components-ui.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-commandnotfound.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-customization-commandnotfound.adoc
similarity index 94%
rename from spring-shell-docs/src/main/asciidoc/using-shell-customization-commandnotfound.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-customization-commandnotfound.adoc
index 5a76a99cd..a3ed12f89 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-commandnotfound.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-customization-commandnotfound.adoc
@@ -1,44 +1,37 @@
[[using-shell-customization-commandnotfound]]
-=== Command Not Found
+= Command Not Found
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
On default a missing command is handled via `CommandNotFoundResultHandler`
and outputs a simple message:
-====
[source, text]
----
shell:>missing
No command found for 'missing'
----
-====
Internally `CommandNotFoundResultHandler` is using `CommandNotFoundMessageProvider`
which is a simple function taking a `ProviderContext` and returning a text
message. Below is an example what a custom message provider might look like.
-====
[source, java, indent=0]
----
include::{snippets}/CommandNotFoundSnippets.java[tag=custom-provider]
----
-====
It's possible to change this implementation by defining it as a bean.
-====
[source, java, indent=0]
----
include::{snippets}/CommandNotFoundSnippets.java[tag=provider-bean-1]
----
-====
`CommandNotFoundResultHandler` is a functional interface so it can
be writter as a lambda.
-====
[source, java, indent=0]
----
include::{snippets}/CommandNotFoundSnippets.java[tag=provider-bean-2]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-logging.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-customization-logging.adoc
similarity index 95%
rename from spring-shell-docs/src/main/asciidoc/using-shell-customization-logging.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-customization-logging.adoc
index 693d732b5..ab3318297 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-logging.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-customization-logging.adoc
@@ -1,5 +1,5 @@
[[using-shell-customization-logging]]
-=== Logging
+= Logging
On default a _Spring Boot_ application will log messages into a console which
at minimum is annoying and may also mix output from a shell commands.
@@ -7,29 +7,24 @@ Fortunately there is a simple way to instruct logging changes via boot propertie
Completely silence console logging by defining its pattern as an empty value.
-====
[source, yaml]
----
logging:
pattern:
console:
----
-====
If you need log from a shell then write those into a file.
-====
[source, yaml]
----
logging:
file:
name: shell.log
----
-====
If you need different log levels.
-====
[source, yaml]
----
logging:
@@ -38,18 +33,15 @@ logging:
springframework:
shell: debug
----
-====
Passing contiguration properties as command line options is not supported but
you can use any other ways supported by boot, for example.
-====
[source, bash]
----
$ java -Dlogging.level.root=debug -jar demo.jar
$ LOGGING_LEVEL_ROOT=debug java -jar demo.jar
----
-====
NOTE: In a GraalVM image settings are locked during compilation which means
you can't change log levels at runtime.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-singlecommand.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-customization-singlecommand.adoc
similarity index 93%
rename from spring-shell-docs/src/main/asciidoc/using-shell-customization-singlecommand.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-customization-singlecommand.adoc
index 192332079..93cfe85d6 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-singlecommand.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-customization-singlecommand.adoc
@@ -1,5 +1,7 @@
[[using-shell-customization-singlecommand]]
-=== Single Command
+= Single Command
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
If your shell application is made for exactly a single purpose having only one
@@ -8,7 +10,6 @@ command it may be beneficial to configure it for this. Property
runners than `NonInteractiveShellRunner` and configures it to use
defined _Primary Command_.
-====
[source, yaml]
----
spring:
@@ -16,7 +17,6 @@ spring:
noninteractive:
primary-command: mycommand
----
-====
For example if you have a command `mycommand` with option `arg`
it had to be executed with ` mycommand --arg hi`, but with above
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-customization-styling.adoc
similarity index 93%
rename from spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-customization-styling.adoc
index 109774ed3..3d478138d 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-customization-styling.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-customization-styling.adoc
@@ -1,5 +1,6 @@
[[theming]]
-=== Theming
+= Theming
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Current terminal implementations are rich in features and can usually show
@@ -12,7 +13,7 @@ Spring Shell supports these via it's theming framework which contains two parts,
firstly _styling_ can be used to change text type and secondly _figures_ how
some characters are shown. These two are then combined together as a _theme_.
-More about _theming_ internals, see <>.
+More about _theming_ internals, see xref:appendices-techical-intro-theming.adoc[Theming].
NOTE: Default theme is named `default` but can be change using property
`spring.shell.theme.name`. Other built-in theme named `dump` uses
@@ -20,49 +21,39 @@ no styling for colors and tries to not use any special figures.
Modify existing style by overriding settings.
-====
[source, java, indent=0]
----
include::{snippets}/ThemingSnippets.java[tag=custom-style-class]
----
-====
Modify existing figures by overriding settings.
-====
[source, java, indent=0]
----
include::{snippets}/ThemingSnippets.java[tag=custom-figure-class]
----
-====
To create a new theme, create a `ThemeSettings` and provide your own _style_
and _figure_ implementations.
-====
[source, java, indent=0]
----
include::{snippets}/ThemingSnippets.java[tag=custom-theme-class]
----
-====
Register a new bean `Theme` where you can return your custom `ThemeSettings`
and a _theme_ name.
-====
[source, java, indent=0]
----
include::{snippets}/ThemingSnippets.java[tag=custom-theme-config]
----
-====
You can use `ThemeResolver` to resolve _styles_ if you want to create
JLine-styled strings programmatically and _figures_ if you want to
theme characters for being more pretty.
-====
[source, java, indent=0]
----
include::{snippets}/ThemingSnippets.java[tag=using-theme-resolver]
----
-====
diff --git a/spring-shell-docs/modules/ROOT/pages/using-shell-customization.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-customization.adoc
new file mode 100644
index 000000000..414086751
--- /dev/null
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-customization.adoc
@@ -0,0 +1,9 @@
+[[using-shell-customization]]
+= Customization
+:page-section-summary-toc: 1
+
+This section describes how you can customize the shell.
+
+
+
+
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-execution.adoc
similarity index 93%
rename from spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-execution.adoc
index d99e856c5..83543ecc5 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-execution.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-execution.adoc
@@ -1,11 +1,12 @@
[[using-shell-execution]]
-== Execution
+= Execution
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
This section describes how to set up a Spring Shell to work in interactive mode.
[[using-shell-execution-interactionmode]]
-=== Interaction Mode
+== Interaction Mode
Version 2.1.x introduced built-in support to distinguish between interactive
and non-interactive modes. This makes it easier to use the shell as a
@@ -13,7 +14,7 @@ simple command-line tool without requiring customization.
Currently, interactive mode is entered if any command line options are passed when starting
or running a shell from a command line. This works especially well when a shell application
-is compiled with <>.
+is compiled with xref:using-shell-building.adoc#native[Native Support].
Some commands may not have any useful meanings when they run in interactive mode
or (conversely) in non-interactive mode. For example, a built-in `exit` command would
@@ -23,7 +24,7 @@ The `@ShellMethod` annotation has a field called `interactionMode` that you can
shell about when a particular command is available.
[[using-shell-execution-shellrunner]]
-=== Shell Runners
+== Shell Runners
`ShellApplicationRunner` is a main interface where Boot's `ApplicationArguments` are passed
and its default implementation makes a choice which `ShellRunner` is used. There can be
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-arity.adoc
similarity index 92%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-arity.adoc
index 53c2dc187..87ed4f8e7 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-arity.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-arity.adoc
@@ -1,5 +1,6 @@
[[using-shell-options-arity]]
-=== Arity
+= Arity
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Arity defines how many parameters option parsing takes.
@@ -8,23 +9,29 @@ NOTE: There are limitations in a `legacy annotation` compared to `annotation`
and `programmatic` use of arity settings. These are mentioned in notes in
below samples.
+[tabs]
+======
+Programmatic::
++
[source,java,indent=0,role="primary"]
-.Programmatic
----
include::{snippets}/OptionSnippets.java[tag=option-registration-zeroorone-programmatic]
----
+Annotation::
++
[source,java,indent=0,role="secondary"]
-.Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-registration-zeroorone-annotation]
----
+Legacy Annotation::
++
[source,java,indent=0,role="secondary"]
-.Legacy Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-registration-zeroorone-legacyannotation]
----
+======
[[using-shell-options-arity-optionarity-table]]
.OptionArity
@@ -50,30 +57,35 @@ include::{snippets}/OptionSnippets.java[tag=option-registration-zeroorone-legacy
NOTE: `legacy annotation` doesn't support defining minimum arity.
+[tabs]
+======
+Programmatic::
++
[source,java,indent=0,role="primary"]
-.Programmatic
----
include::{snippets}/OptionSnippets.java[tag=option-registration-zerooronewithminmax-programmatic]
----
+Annotation::
++
[source,java,indent=0,role="secondary"]
-.Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-registration-zerooronewithminmax-annotation]
----
+Legacy Annotation::
++
[source,java,indent=0,role="secondary"]
-.Legacy Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-registration-zerooronewithminmax-legacyannotation]
----
+======
In below example we have option _arg1_ and it's defined as type _String[]_. Arity
defines that it needs at least 1 parameter and not more that 2. As seen in below
spesific exceptions _TooManyArgumentsOptionException_ and
_NotEnoughArgumentsOptionException_ are thrown to indicate arity mismatch.
-====
[source, bash]
----
shell:>e2e reg arity-errors --arg1
@@ -88,4 +100,3 @@ Hello [one, two]
shell:>e2e reg arity-errors --arg1 one two three
Too many arguments --arg1 requires at most 2.
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-basics-annotation.adoc
similarity index 88%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-basics-annotation.adoc
index 227217f5f..60f134d41 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-annotation.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-basics-annotation.adoc
@@ -1,13 +1,13 @@
[[using-shell-options-basics-annotation]]
-==== Annotation
+= Annotation
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
`Option` annotation can be used to define an option name if you
don't want it to be same as argument name.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-with-option-annotation]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-basics-legacyannotation.adoc
similarity index 93%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-basics-legacyannotation.adoc
index 3558bc845..dc52072f3 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-legacyannotation.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-basics-legacyannotation.adoc
@@ -1,33 +1,28 @@
[[using-shell-options-basics-legacyannotation]]
-==== Legacy Annotation
+= Legacy Annotation
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Having a target method with argument is automatically registered with a matching
argument name.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-without-annotation]
----
-====
`@ShellOption` annotation can be used to define an option name if you
don't want it to be same as argument name.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-with-annotation]
----
-====
If option name is defined without prefix, either `-` or `--`, it is discovered
from _ShellMethod#prefix_.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-with-annotation-without-prefix]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-programmatic.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-basics-programmatic.adoc
similarity index 92%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-basics-programmatic.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-basics-programmatic.adoc
index 2f7e93ba1..8a61da1fe 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics-programmatic.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-basics-programmatic.adoc
@@ -1,17 +1,17 @@
[[using-shell-options-basics-registration]]
[[using-shell-options-basics-programmatic]]
-==== Programmatic
+= Programmatic
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Programmatic way with `CommandRegistration` is to use `withOption` to define
an option.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-registration-longarg]
----
-====
`CommandRegistration` can be defined as a bean or manually registered
with a `CommandCatalog`.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-basics.adoc
similarity index 62%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-basics.adoc
index e5ce2638c..6a155c31b 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-basics.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-basics.adoc
@@ -1,13 +1,12 @@
[[using-shell-options-basics]]
-=== Basics
+= Basics
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
This section gives a generic idea how an option can be defined. Following
sections, beyond basics, discuss more about how various option behaviour
can be accomplished for a particular use case.
-include::using-shell-options-basics-programmatic.adoc[]
-include::using-shell-options-basics-annotation.adoc[]
-include::using-shell-options-basics-legacyannotation.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-default.adoc
similarity index 78%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-default.adoc
index 0bb54ef8d..2dcbab8c9 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-default.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-default.adoc
@@ -1,26 +1,33 @@
[[using-shell-options-default]]
-=== Default Value
+= Default Value
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Having a default value for an option is somewhat related to
-<>, as there are cases where you
+xref:using-shell-options-optional.adoc[Optional Value], as there are cases where you
may want to know if the user defined an option and change behavior
based on a default value:
+[tabs]
+======
+Programmatic::
++
[source,java,indent=0,role="primary"]
-.Programmatic
----
include::{snippets}/OptionSnippets.java[tag=option-default-programmatic]
----
+Annotation::
++
[source,java,indent=0,role="secondary"]
-.Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-default-annotation]
----
+Legacy Annotation::
++
[source,java,indent=0,role="secondary"]
-.Legacy Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-default-legacyannotation]
----
+======
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-label.adoc
similarity index 93%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-label.adoc
index c2f8ccc5e..726c85346 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-label.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-label.adoc
@@ -1,5 +1,6 @@
[[using-shell-options-label]]
-=== Label
+= Label
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
_Option Label_ has no functional behaviour within a shell itself other than
@@ -9,20 +10,24 @@ you may want to give better descriptive word for an option.
NOTE: Label is not supported with `legacy annotation`.
+[tabs]
+======
+Programmatic::
++
[source,java,indent=0,role="primary"]
-.Programmatic
----
include::{snippets}/OptionSnippets.java[tag=option-label-programmatic]
----
+Annotation::
++
[source,java,indent=0,role="secondary"]
-.Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-label-annotation]
----
+======
Defining label is then shown in `help`.
-====
[source, bash]
----
my-shell:>help labelOption
@@ -37,4 +42,3 @@ OPTIONS
[Optional]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-naming.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-naming.adoc
similarity index 97%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-naming.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-naming.adoc
index ba9c9c501..d224b9248 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-naming.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-naming.adoc
@@ -1,5 +1,6 @@
[[using-shell-options-naming]]
-=== Naming
+= Naming
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
If there is a need to modify option long names that can be done
@@ -15,22 +16,18 @@ on default.
You can define one with an option in `CommandRegistration`.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-registration-naming-case-req]
----
-====
Add one _singleton bean_ as type `OptionNameModifier` and that becomes
a global default.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-registration-naming-case-bean]
----
-====
It's also possible to just add configuration property with
`spring.shell.option.naming.case-type` which auto-configures
@@ -45,7 +42,6 @@ default via configuration properies only work if using
pre-configured `Builder` instance. See more
<>.
-====
[source, yaml]
----
spring:
@@ -58,21 +54,17 @@ spring:
# case-type: kebab
# case-type: pascal
----
-====
For example options defined in an annotated method like this.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-registration-naming-case-sample1]
----
-====
On default `help` for that command shows names coming
directly from `@ShellOption`.
-====
[source, bash]
----
OPTIONS
@@ -88,12 +80,10 @@ OPTIONS
--FromPascal String
[Mandatory]
----
-====
Define `spring.shell.option.naming.case-type=kebab` and default
modifier is added and option names then look like.
-====
[source, bash]
----
OPTIONS
@@ -110,4 +100,3 @@ OPTIONS
[Mandatory]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-optional.adoc
similarity index 85%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-optional.adoc
index e8bc088fb..ee0d3b4ac 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-optional.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-optional.adoc
@@ -1,5 +1,6 @@
[[using-shell-options-optional]]
-=== Optional Value
+= Optional Value
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
An option is either required or not and, generally speaking, how it behaves depends on
@@ -7,40 +8,52 @@ a command target.
Making option optional.
+[tabs]
+======
+Programmatic::
++
[source,java,indent=0,role="primary"]
-.Programmatic
----
include::{snippets}/OptionSnippets.java[tag=option-optional-programmatic]
----
+Annotation::
++
[source,java,indent=0,role="secondary"]
-.Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-optional-annotation]
----
+Legacy Annotation::
++
[source,java,indent=0,role="secondary"]
-.Legacy Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-optional-legacyannotation]
----
+======
Making option mandatory.
+[tabs]
+======
+Programmatic::
++
[source,java,indent=0,role="primary"]
-.Programmatic
----
include::{snippets}/OptionSnippets.java[tag=option-mandatory-programmatic]
----
+Annotation::
++
[source,java,indent=0,role="secondary"]
-.Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-mandatory-annotation]
----
+Legacy Annotation::
++
[source,java,indent=0,role="secondary"]
-.Legacy Annotation
----
include::{snippets}/OptionSnippets.java[tag=option-mandatory-legacyannotation]
----
+======
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-positional.adoc
similarity index 96%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-positional.adoc
index b54563cdf..608c07265 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-positional.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-positional.adoc
@@ -1,15 +1,14 @@
[[using-shell-options-positional]]
-=== Positional
+= Positional
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Positional information is mostly related to a command target method:
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-registration-positional]
----
-====
NOTE: Be careful with positional parameters as it may soon
become confusing which options those are mapped to.
@@ -26,36 +25,29 @@ ambiguous arguments.
Let's look what happens when we don't define a position.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-registration-aritystrings-noposition]
----
-====
Option _arg1_ is required and there is no info what to do with argument
`one` resulting error for missing option.
-====
[source, bash]
----
shell:>arity-strings-1 one
Missing mandatory option --arg1.
----
-====
Now let's define a position `0`.
-====
[source, java, indent=0]
----
include::{snippets}/OptionSnippets.java[tag=option-registration-aritystrings-position]
----
-====
Arguments are processed until we get up to 2 arguments.
-====
[source, bash]
----
shell:>arity-strings-2 one
@@ -67,4 +59,3 @@ Hello [one, two]
shell:>arity-strings-2 one two three
Hello [one, two]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-short.adoc
similarity index 88%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-short.adoc
index 74fce3939..b6f11d5e9 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-short.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-short.adoc
@@ -1,46 +1,59 @@
[[using-shell-options-short]]
-=== Short Format
+= Short Format
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Short style _POSIX_ option is usually just a synonym to long format. As
shown below option `--arg` is equal to `-a`.
+[tabs]
+======
+Programmatic::
++
[source,java,indent=0,role="primary"]
-.Programmatic
----
include::{snippets}/ShortOptionSnippets.java[tag=option-type-string-programmatic]
----
+Annotation::
++
[source,java,indent=0,role="secondary"]
-.Annotation
----
include::{snippets}/ShortOptionSnippets.java[tag=option-type-string-annotation]
----
+Legacy Annotation::
++
[source,java,indent=0,role="secondary"]
-.Legacy Annotation
----
include::{snippets}/ShortOptionSnippets.java[tag=option-type-string-legacyannotation]
----
+======
Short option with combined format is powerful if type is defined as a flag
which means type is a _boolean_. That way you can define a presence of a flags
as `-abc`, `-abc true` or `-abc false`.
+[tabs]
+======
+Programmatic::
++
[source,java,indent=0,role="primary"]
-.Programmatic
----
include::{snippets}/ShortOptionSnippets.java[tag=option-type-multiple-booleans-programmatic]
----
+Annotation::
++
[source,java,indent=0,role="secondary"]
-.Annotation
----
include::{snippets}/ShortOptionSnippets.java[tag=option-type-multiple-booleans-annotation]
----
+Legacy Annotation::
++
[source,java,indent=0,role="secondary"]
-.Legacy Annotation
----
include::{snippets}/ShortOptionSnippets.java[tag=option-type-multiple-booleans-legacyannotation]
----
+======
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-types.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-types.adoc
similarity index 92%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-types.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-types.adoc
index fac265bbf..072b5a30d 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-types.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-types.adoc
@@ -1,45 +1,41 @@
[[using-shell-options-types]]
-=== Types
+= Types
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
This section talks about how particular data type is used as an option value.
-==== String
+[[string]]
+== String
`String` is a most simplest type as there's no conversion involved as what's
coming in from a user is always a string.
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-anno]
----
-====
While it's not strictly required to define type as a `String` it's always
adviced to do so.
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-reg]
----
-====
-==== Boolean
+[[boolean]]
+== Boolean
Using boolean types is a bit more involved as there are `boolean` and
`Boolean` where latter can be _null_. Boolean types are usually used as
flags meaning argument value may not be needed.
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-boolean-anno]
----
-====
-====
[source, bash]
----
shell:>example
@@ -51,16 +47,12 @@ arg1=false arg2=true arg3=false arg4=true arg5=true arg6=false
shell:>example --arg4 false
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
----
-====
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-boolean-reg]
----
-====
-====
[source, bash]
----
shell:>example
@@ -72,66 +64,54 @@ arg1=false arg2=true arg3=false arg4=true arg5=true arg6=false
shell:>example --arg4 false
arg1=false arg2=true arg3=false arg4=false arg5=true arg6=false
----
-====
-==== Number
+[[number]]
+== Number
Numbers are converted as is.
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-integer-anno]
----
-====
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-integer-reg]
----
-====
-==== Enum
+[[enum]]
+== Enum
Conversion to enums is possible if given value is exactly matching enum itself.
Currently you can convert assuming case insensitivity.
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-class]
----
-====
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-anno]
----
-====
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-enum-reg]
----
-====
-==== Array
+[[array]]
+== Array
Arrays can be used as is with strings and primitive types.
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-array-anno]
----
-====
-====
[source, java, indent=0]
----
include::{snippets}/OptionTypesSnippets.java[tag=option-type-string-array-reg]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options-validation.adoc
similarity index 95%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options-validation.adoc
index 9676a8148..7f7862251 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-validation.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options-validation.adoc
@@ -1,5 +1,5 @@
[[validating-command-arguments]]
-=== Validation
+= Validation
Spring Shell integrates with the https://beanvalidation.org/[Bean Validation API] to support
automatic and self-documenting constraints on command parameters.
@@ -7,7 +7,6 @@ automatic and self-documenting constraints on command parameters.
Annotations found on command parameters and annotations at the method level are
honored and trigger validation prior to the command executing. Consider the following command:
-====
[source, java]
----
@ShellMethod("Change password.")
@@ -15,14 +14,11 @@ honored and trigger validation prior to the command executing. Consider the foll
return "Password successfully set to " + password;
}
----
-====
From the preceding example, you get the following behavior for free:
-====
----
shell:>change-password hello
The following constraints were not met:
--password string : size must be between 8 and 40 (You passed 'hello')
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-options.adoc
similarity index 64%
rename from spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-options.adoc
index 09b9289b6..04b0532e0 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-options.adoc
@@ -1,5 +1,6 @@
[[using-shell-options]]
-== Options
+= Options
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Command line arguments can be separated into options and positional parameters.
@@ -17,22 +18,12 @@ arguments or with programmatically using `CommandRegistration`.
NOTE: In below sections `@ShellOption` refer to a _legacy annotation model_
and `@Option` refer to an _annotation model_.
-include::using-shell-options-basics.adoc[]
-include::using-shell-options-short.adoc[]
-include::using-shell-options-arity.adoc[]
-include::using-shell-options-positional.adoc[]
-include::using-shell-options-optional.adoc[]
-include::using-shell-options-default.adoc[]
-include::using-shell-options-validation.adoc[]
-include::using-shell-options-label.adoc[]
-include::using-shell-options-types.adoc[]
-include::using-shell-options-naming.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-testing-basics.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-testing-basics.adoc
similarity index 95%
rename from spring-shell-docs/src/main/asciidoc/using-shell-testing-basics.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-testing-basics.adoc
index d572aee11..7535eb602 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-testing-basics.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-testing-basics.adoc
@@ -1,5 +1,6 @@
[[using-shell-testing-basics]]
-=== Basics
+= Basics
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Spring Shell provides a number of utilities and annotations to help when testing your application.
@@ -8,18 +9,14 @@ Test support is provided by two modules: `spring-shell-test` contains core items
To test _interactive_ commands.
-====
[source, java, indent=0]
----
include::{snippets}/TestingSnippets.java[tag=testing-shelltest-interactive]
----
-====
To test _non-interactive_ commands.
-====
[source, java, indent=0]
----
include::{snippets}/TestingSnippets.java[tag=testing-shelltest-noninteractive]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-testing-settings.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-testing-settings.adoc
similarity index 95%
rename from spring-shell-docs/src/main/asciidoc/using-shell-testing-settings.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-testing-settings.adoc
index 851a0c5ee..c01c4c8e9 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-testing-settings.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-testing-settings.adoc
@@ -1,5 +1,6 @@
[[using-shell-testing-settings]]
-=== Settings
+= Settings
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Built in emulation uses terminal width 80 and height 24 on default.
@@ -9,19 +10,15 @@ lines and you don't want to handle those cases in a tests.
These can be changed using properties `spring.shell.test.terminal-width`
or `spring.shell.test.terminal-height`.
-====
[source, java, indent=0]
----
include::{snippets}/TestingSnippets.java[tag=testing-shelltest-dimensions-props]
----
-====
`ShellTest` annotation have fields `terminalWidth` and `terminalHeight`
which can also be used to change dimensions.
-====
[source, java, indent=0]
----
include::{snippets}/TestingSnippets.java[tag=testing-shelltest-dimensions-field]
----
-====
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-testing.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-testing.adoc
similarity index 86%
rename from spring-shell-docs/src/main/asciidoc/using-shell-testing.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-testing.adoc
index b2e5e3fba..34e4d5054 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-testing.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-testing.adoc
@@ -1,5 +1,7 @@
[[using-shell-testing]]
-== Testing
+= Testing
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Testing cli application is difficult due to various reasons:
@@ -15,6 +17,4 @@ Testing cli application is difficult due to various reasons:
NOTE: Testing support is currently under development and will be
unstable for various parts.
-include::using-shell-testing-basics.adoc[]
-include::using-shell-testing-settings.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-tui-intro.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-tui-intro.adoc
similarity index 89%
rename from spring-shell-docs/src/main/asciidoc/using-shell-tui-intro.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-tui-intro.adoc
index 6c2d803cc..6e71bde06 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-tui-intro.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-tui-intro.adoc
@@ -1,14 +1,14 @@
[[using-shell-tui-intro]]
-=== Introduction
+= Introduction
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Lets start with a simple app which prints "hello world" in a view.
-====
[source, java, indent=0]
----
include::{snippets}/TerminalUiSnippets.java[tag=snippet1]
----
-====
There is not much to see here other than `TerminalUI` is a class handling
all logic aroung views and uses `View` as it's root view.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-tui-views-box.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-tui-views-box.adoc
similarity index 83%
rename from spring-shell-docs/src/main/asciidoc/using-shell-tui-views-box.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-tui-views-box.adoc
index 719f99fe6..1c6e664dd 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-tui-views-box.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-tui-views-box.adoc
@@ -1,5 +1,7 @@
[[using-shell-tui-views-box]]
-==== BoxView
+= BoxView
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
_BoxView_ is a base implementation providing functionality to draw into a
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-tui-views-list.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-tui-views-list.adoc
similarity index 82%
rename from spring-shell-docs/src/main/asciidoc/using-shell-tui-views-list.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-tui-views-list.adoc
index 1a2504c04..0cb9530c1 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-tui-views-list.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-tui-views-list.adoc
@@ -1,5 +1,7 @@
[[using-shell-tui-views-list]]
-==== ListView
+= ListView
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
_ListView_ is a base implementation providing functionality to draw list of items.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-tui-views.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-tui-views.adoc
similarity index 52%
rename from spring-shell-docs/src/main/asciidoc/using-shell-tui-views.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-tui-views.adoc
index 1b806c3ea..b4eb81515 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-tui-views.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-tui-views.adoc
@@ -1,11 +1,11 @@
[[using-shell-tui-views]]
-=== Views
+= Views
+:page-section-summary-toc: 1
+
ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
Framework provides a build-in views which are documented below.
-TIP: To learn more about views, see <>.
+TIP: To learn more about views, see xref:appendices-tui-view.adoc[View].
-include::using-shell-tui-views-box.adoc[]
-include::using-shell-tui-views-list.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-tui.adoc b/spring-shell-docs/modules/ROOT/pages/using-shell-tui.adoc
similarity index 67%
rename from spring-shell-docs/src/main/asciidoc/using-shell-tui.adoc
rename to spring-shell-docs/modules/ROOT/pages/using-shell-tui.adoc
index 2fa4aacb4..a8823bc62 100644
--- a/spring-shell-docs/src/main/asciidoc/using-shell-tui.adoc
+++ b/spring-shell-docs/modules/ROOT/pages/using-shell-tui.adoc
@@ -1,16 +1,15 @@
[[using-shell-tui]]
-== Terminal UI
+= Terminal UI
+:page-section-summary-toc: 1
NOTE: Feature is experimental and subject to breaking changes until foundation
and related concepts around framework are getting more stable.
_Terminal UI Framework_ is a toolkit to build rich console apps. This section is
for those using existing features as is. If you're planning to go deeper possibly
-creating your own components <> provides more detailed
+creating your own components xref:appendices-tui.adoc[Terminal UI] provides more detailed
documentation.
-TIP: Catalog sample is a good place to study a real application <>.
+TIP: Catalog sample is a good place to study a real application xref:appendices-tui-catalog.adoc[Catalog App].
-include::using-shell-tui-intro.adoc[]
-include::using-shell-tui-views.adoc[]
diff --git a/spring-shell-docs/spring-shell-docs.gradle b/spring-shell-docs/spring-shell-docs.gradle
index 74c54b9d4..4eb4e3f49 100644
--- a/spring-shell-docs/spring-shell-docs.gradle
+++ b/spring-shell-docs/spring-shell-docs.gradle
@@ -1,5 +1,7 @@
plugins {
id 'org.springframework.shell.docs'
+ id 'org.antora' version '1.0.0'
+ id 'io.spring.antora.generate-antora-yml' version '0.0.1'
}
description = 'Spring Shell Documentation'
@@ -12,6 +14,32 @@ dependencies {
testImplementation 'org.awaitility:awaitility'
}
-asciidoctorj {
- version = '2.5.4'
+antora {
+ version = '3.2.0-alpha.2'
+ options = [clean: true, fetch: !project.gradle.startParameter.offline, stacktrace: true]
+ dependencies = [
+ '@antora/atlas-extension': '1.0.0-alpha.1',
+ '@antora/collector-extension': '1.0.0-alpha.3',
+ '@asciidoctor/tabs': '1.0.0-beta.3',
+ '@springio/antora-extensions': '1.4.2',
+ '@springio/asciidoctor-extensions': '1.0.0-alpha.8',
+ ]
}
+
+tasks.named("generateAntoraYml") {
+ asciidocAttributes = project.provider( {
+ def dependencies = resolvedVersions(project.configurations.testRuntimeClasspath)
+ return ['project-version' : project.version,
+ 'spring-boot-version' : dependencies['spring-boot-starter-version'],
+ 'spring-version': dependencies['spring-core-version']
+ ]
+ } )
+}
+
+
+
+def resolvedVersions(Configuration configuration) {
+ return configuration.resolvedConfiguration
+ .resolvedArtifacts
+ .collectEntries { [(it.name + '-version'): it.moduleVersion.id.version] }
+}
\ No newline at end of file
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc b/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc
deleted file mode 100644
index cf835df2c..000000000
--- a/spring-shell-docs/src/main/asciidoc/appendices-techical-intro.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[appendix]
-[#appendix-tech-intro]
-== Techical Introduction
-This appendix contains information for developers and others who would like to know more about how Spring Shell
-works internally and what its design decisions are.
-
-include::appendices-techical-intro-registration.adoc[]
-
-include::appendices-techical-intro-parser.adoc[]
-
-include::appendices-techical-intro-execution.adoc[]
-
-include::appendices-techical-intro-commandcontext.adoc[]
-
-include::appendices-techical-intro-commandcatalog.adoc[]
-
-include::appendices-techical-intro-theming.adoc[]
-
-include::appendices-techical-intro-searchalgorithm.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/appendices-tui.adoc b/spring-shell-docs/src/main/asciidoc/appendices-tui.adoc
deleted file mode 100644
index 0ffe605f9..000000000
--- a/spring-shell-docs/src/main/asciidoc/appendices-tui.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[appendix]
-[#appendix-tech-intro-tui]
-== Terminal UI
-ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
-
-This is a technical introduction to _UI Framework_.
-
-_UI Framework_ is a toolkit to build rich console apps.
-
-include::appendices-tui-control.adoc[]
-
-include::appendices-tui-view.adoc[]
-
-include::appendices-tui-eventloop.adoc[]
-
-include::appendices-tui-screen.adoc[]
-
-include::appendices-tui-keyhandling.adoc[]
-
-include::appendices-tui-mousehandling.adoc[]
-
-include::appendices-tui-catalog.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/appendices.adoc b/spring-shell-docs/src/main/asciidoc/appendices.adoc
deleted file mode 100644
index ba48fdfe4..000000000
--- a/spring-shell-docs/src/main/asciidoc/appendices.adoc
+++ /dev/null
@@ -1,5 +0,0 @@
-include::appendices-techical-intro.adoc[]
-
-include::appendices-debugging.adoc[]
-
-include::appendices-tui.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/index.adoc b/spring-shell-docs/src/main/asciidoc/index.adoc
deleted file mode 100644
index 7b9c115ad..000000000
--- a/spring-shell-docs/src/main/asciidoc/index.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-= Spring Shell Reference Documentation
-Eric Bottard; Janne Valkealahti; Jay Bryant; Corneil du Plessis
-:doctype: book
-:hide-uri-scheme:
-:icons: font
-:experimental: // For kbd: macro
-:spring-shell-starter: spring-shell-starter
-
-*{project-version}*
-
-(C) 2017 - 2023 VMware, Inc.
-
-_Copies of this document may be made for your own use and for distribution to
-others, provided that you do not charge any fee for such copies and further
-provided that each copy contains this Copyright Notice, whether distributed in
-print or electronically._
-
-include::introduction.adoc[]
-
-include::getting-started.adoc[]
-
-include::using-shell.adoc[]
-
-include::appendices.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/introduction.adoc b/spring-shell-docs/src/main/asciidoc/introduction.adoc
deleted file mode 100644
index 2e871523c..000000000
--- a/spring-shell-docs/src/main/asciidoc/introduction.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-== What is Spring Shell?
-Not all applications need a fancy web user interface.
-Sometimes, interacting with an application through an interactive terminal is
-the most appropriate way to get things done.
-
-Spring Shell lets you create such a runnable application, where the
-user enters textual commands that are run until the program terminates.
-The Spring Shell project provides the infrastructure to create such a REPL (Read, Eval,
-Print Loop) application, letting you concentrate on implementing commands by using
-the familiar Spring programming model.
-
-Spring Shell includes advanced features (such as parsing, tab completion, colorization of
-output, fancy ASCII-art table display, input conversion, and validation), freeing you
-to focus on core command logic.
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin.adoc
deleted file mode 100644
index f8aabfbce..000000000
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands-builtin.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[built-in-commands]]
-=== Built-In Commands
-
-include::using-shell-commands-builtin-help.adoc[]
-
-include::using-shell-commands-builtin-clear.adoc[]
-
-include::using-shell-commands-builtin-exit.adoc[]
-
-include::using-shell-commands-builtin-stacktrace.adoc[]
-
-include::using-shell-commands-builtin-script.adoc[]
-
-include::using-shell-commands-builtin-history.adoc[]
-
-include::using-shell-commands-builtin-completion.adoc[]
-
-include::using-shell-commands-builtin-version.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
deleted file mode 100644
index a8053aced..000000000
--- a/spring-shell-docs/src/main/asciidoc/using-shell-commands.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-== Commands
-ifndef::snippets[:snippets: ../../test/java/org/springframework/shell/docs]
-
-In this section, we go through an actual command registration and leave command options
-and execution for later in a documentation. You can find more detailed info in
-<>.
-
-include::using-shell-commands-registration.adoc[]
-
-include::using-shell-commands-organize.adoc[]
-
-include::using-shell-commands-availability.adoc[]
-
-include::using-shell-commands-exceptionhandling.adoc[]
-
-include::using-shell-commands-hidden.adoc[]
-
-include::using-shell-commands-helpoptions.adoc[]
-
-include::using-shell-commands-interactionmode.adoc[]
-
-include::using-shell-commands-builtin.adoc[]
-
-include::using-shell-commands-writing.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc
deleted file mode 100644
index e1c80c1c3..000000000
--- a/spring-shell-docs/src/main/asciidoc/using-shell-customization.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[using-shell-customization]]
-== Customization
-
-This section describes how you can customize the shell.
-
-include::using-shell-customization-styling.adoc[]
-
-include::using-shell-customization-logging.adoc[]
-
-include::using-shell-customization-commandnotfound.adoc[]
-
-include::using-shell-customization-singlecommand.adoc[]
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc b/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc
deleted file mode 100644
index ad1dd5e23..000000000
--- a/spring-shell-docs/src/main/asciidoc/using-shell-options-generic.adoc
+++ /dev/null
@@ -1,359 +0,0 @@
-==== Invoking your Commands
-
-This section addresses how you can control the way in which your commands are invoked.
-
-===== By Name Versus Positional Parameters
-
-As seen <>, decorating a method with `@ShellMethod` is the sole requirement for creating a command.
-
-The user can set the value of all the method parameters in either of two ways:
-
-* By using a parameter key (for example, `--arg value`). This approach is called "`by name parameters.`"
-* Without a key, by setting parameter values in the order in which they appear in the method signature (called "`positional parameters`").
-
-These two approaches can be mixed and matched, with named parameters always taking precedence (as they are less
-prone to ambiguity). Consider the following command definition:
-
-====
-[source, java]
-----
- @ShellMethod("Display stuff.")
- public String echo(int a, int b, int c) {
- return String.format("You said a=%d, b=%d, c=%d", a, b, c);
- }
-----
-====
-
-Given the preceding command definiton, the following invocations are all equivalent, as shown in the output:
-
-====
-[source, bash]
-----
-shell:>echo 1 2 3 <1>
-You said a=1, b=2, c=3
-
-shell:>echo --a 1 --b 2 --c 3 <2>
-You said a=1, b=2, c=3
-
-shell:>echo --b 2 --c 3 --a 1 <3>
-You said a=1, b=2, c=3
-
-shell:>echo --a 1 2 3 <4>
-You said a=1, b=2, c=3
-
-shell:>echo 1 --c 3 2 <5>
-You said a=1, b=2, c=3
-----
-<1> This uses positional parameters.
-<2> This is an example of full by-name parameters.
-<3> By-name parameters can be reordered as desired.
-<4> You can use a mix of the two approaches.
-<5> The non by-name parameters are resolved in the order in which they appear.
-====
-
-====== Customizing the Named Parameter Keys
-
-As seen <>, the default strategy for deriving the key for a named parameter is to use the Java
-name of the method signature and prefix it with two dashes (`--`). You can customize this in two ways:
-
-* Use the `prefix()` attribute of the `@ShellMethod` annotation to change the default prefix for the whole method.
-* Annotate the parameter with the `@ShellOption` annotation to override the entire key in a per-parameter fashion.
-
-Consider the following example:
-
-====
-[source, java]
-----
- @ShellMethod(value = "Display stuff.", prefix="-")
- public String echo(int a, int b, @ShellOption("--third") int c) {
- return String.format("You said a=%d, b=%d, c=%d", a, b, c);
- }
-----
-====
-
-For such a setup, the possible parameter keys are `-a`, `-b` and `--third`.
-
-[TIP]
-=====
-You can specify several keys for a single parameter. If you do so, these keys are mutually exclusive (only one of them can be used) ways
-to specify the same parameter. The following example shows the signature of the
-built-in <> command:
-
-====
-[source, java]
-----
- @ShellMethod("Describe a command.")
- public String help(@ShellOption({"-C", "--command"}) String command) {
- ...
- }
-----
-====
-=====
-
-[[optional-parameters-default-values]]
-===== Optional Parameters and Default Values
-
-Spring Shell provides the ability to give parameters default values, which lets users omit
-those parameters. Consider the following command definition:
-
-====
-[source, java]
-----
- @ShellMethod("Say hello.")
- public String greet(@ShellOption(defaultValue="World") String who) {
- return "Hello " + who;
- }
-----
-====
-
-With the preceding definition, the `greet` command can still be invoked as `greet Mother` (or `greet --who Mother`), but the following
-is also possible:
-
-====
-[source]
-----
-shell:>greet
-Hello World
-----
-====
-
-===== Parameter Arity
-Up to now, it has always been assumed that each parameter maps to a single word entered by the user.
-Situations may arise, though, when a parameter value should be multi-valued. This is driven by the `arity()`
-attribute of the `@ShellOption` annotation. You can use a collection or array for the parameter type and specify how
-many values are expected:
-
-====
-[source, java]
-----
- @ShellMethod("Add Numbers.")
- public float add(@ShellOption(arity=3) float[] numbers) {
- return numbers[0] + numbers[1] + numbers[2];
- }
-----
-====
-
-The users can then invoke the command by using any of the following syntax:
-
-====
-[source]
-----
-shell:>add 1 2 3.3
-6.3
-shell:>add --numbers 1 2 3.3
-6.3
-----
-====
-
-[WARNING]
-=====
-When using the _by-name_ parameter approach, the key should *not* be repeated. The following does *not* work:
-
-====
-[source]
-----
-shell:>add --numbers 1 --numbers 2 --numbers 3.3
-----
-====
-=====
-
-====== Varying Amount Arity
-
-The above example demonstrates requiring a known, constant arity for a parameter, three in this case. Allowing any number of multiple values of a parameter can be achieved by leaving `arity` unspecified and using Spring's built-in comma separated value parsing for collections and/or arrays:
-[source, java]
-----
- @ShellMethod("Add a Varying Amount of Numbers.")
- public double add(@ShellOption double[] numbers) {
- return Arrays.stream(numbers).sum();
- }
-----
-
-The command may then be invoked with any amount of `numbers`:
-
-====
-[source]
-----
-shell:>add 1,2,3.3
-6.3
-shell:>add --numbers 42
-42.0
-shell:>add --numbers 1,2,3.3,4,5
-15.3
-----
-====
-
-====== Special Handling of Boolean Parameters
-
-When it comes to parameter arity, one kind of parameter receives a special treatment by default, as
-is often the case in command-line utilities.
-Boolean (that is, `boolean` as well as `java.lang.Boolean`) parameters behave like they have an `arity()` of `0` by default, allowing users to set their values by using a "`flag`" approach.
-Consider the following command definition:
-
-====
-[source, java]
-----
- @ShellMethod("Terminate the system.")
- public String shutdown(boolean force) {
- return "You said " + force;
- }
-----
-====
-
-This preceding command definition allows the following invocations:
-
-====
-[source]
-----
-shell:>shutdown
-You said false
-shell:>shutdown --force
-You said true
-----
-====
-
-TIP: This special treatment plays well with the <> specification. Although the default
-for boolean parameters is to have their default value be `false`, you can specify otherwise (that is,
-`@ShellOption(defaultValue="true")`), and the behavior is inverted (that is, not specifying the parameter
-results in the value being `true`, and specifying the flag results in the value being `false`)
-
-[WARNING]
-=====
-Having this behavior of implicit `arity()=0` prevents the user from specifying a value (for example, `shutdown --force true`).
-If you would like to allow this behavior (and forego the flag approach), then force an arity of `1` by using the annotation as follows:
-
-====
-[source, java]
-----
- @ShellMethod("Terminate the system.")
- public String shutdown(@ShellOption(arity=1, defaultValue="false") boolean force) {
- return "You said " + force;
- }
-----
-====
-=====
-
-[[quotes-handling]]
-===== Quotes Handling
-
-Spring Shell takes user input and tokenizes it into words, splitting on space characters.
-If the user wants to provide a parameter value that contains spaces, that value needs to be quoted.
-Both single (`'`) and double (`"`) quotes are supported, and those quotes are not part of the value:
-Consider the following command definition:
-
-====
-[source, java]
-----
- @ShellMethod("Prints what has been entered.")
- public String echo(String what) {
- return "You said " + what;
- }
-----
-====
-
-The following commands all invoke the preceding command definition:
-
-====
-[source]
-----
-shell:>echo Hello
-You said Hello
-shell:>echo 'Hello'
-You said Hello
-shell:>echo 'Hello World'
-You said Hello World
-shell:>echo "Hello World"
-You said Hello World
-----
-====
-
-Supporting both single and double quotes lets the user embed one type of quotes into
-a value:
-
-====
-[source]
-----
-shell:>echo "I'm here!"
-You said I'm here!
-shell:>echo 'He said "Hi!"'
-You said He said "Hi!"
-----
-====
-
-That way, the user can use a single quote as an apostrophe in a message.
-
-Should the user need to embed the same kind of quote that was used to quote the whole parameter,
-the escape sequence uses the backslash (`\`) character:
-
-====
-[source]
-----
-shell:>echo 'I\'m here!'
-You said I'm here!
-shell:>echo "He said \"Hi!\""
-You said He said "Hi!"
-shell:>echo I\'m here!
-You said I'm here!
-----
-====
-
-It is also possible to escape space characters when not using enclosing quotes:
-
-====
-[source]
-----
-shell:>echo This\ is\ a\ single\ value
-You said This is a single value
-----
-====
-
-[[interacting-with-the-shell]]
-===== Interacting with the Shell
-
-The Spring Shell project builds on top of the https://github.com/jline/jline3[JLine] library and, as a result, brings
-a lot of nice interactive features, some of which are detailed in this section.
-
-First and foremost, Spring Shell supports tab completion almost everywhere possible. So, if there
-is an `echo` command and the user types `ec` and presses `TAB`, `echo` appears.
-Should there be several commands that start with `ec`, then the user is prompted to choose (using `TAB` or
-`Shift + TAB` to navigate and `ENTER` to select.)
-
-But completion does not stop at command keys. It also works for parameter keys (`--arg`) and even
-parameter values, if the application developer registered the appropriate beans (see <>).
-
-Another nice feature of Spring Shell applications is support for line continuation. If a command and its parameters
-is too long and does not fit nicely on the screen, a user can chunk it by ending a line with a backslash
-(`\`) character, pressing `ENTER`, and continuing on the next line. Upon submission of the whole command, this is
-parsed as if the user entered a single space on line breaks. The following listing shows an example of this behavior:
-
-====
-[source]
-----
-shell:>register module --type source --name foo \ <1>
-> --uri file:///tmp/bar
-Successfully registered module 'source:foo'
-----
-<1> command continues on next line
-====
-
-Line continuation also automatically triggers if the user has opened a quote (see <>)
-and presses `ENTER` while still in the quotes:
-
-====
-[source]
-----
-shell:>echo "Hello <1>
-dquote> World"
-You said Hello World
-----
-<1> The user pressed `ENTER` here.
-====
-
-Finally, Spring Shell applications benefit from a lot of keyboard shortcuts (borrowed from Emacs) with which you may
-already be familiar from working with your regular OS Shell. Notable shortcuts include `Ctrl+r` to perform
-a reverse search, `Ctrl+a`] and `Ctrl+e` to move to the beginning and the end of the current line (respectively),
-and `Esc f` and `Esc b` to move forward or backward (respectively) one word at a time.
-
-[[providing-tab-completion]]
-// ===== Providing TAB Completion Proposals
-
-// TBD
diff --git a/spring-shell-docs/src/main/asciidoc/using-shell.adoc b/spring-shell-docs/src/main/asciidoc/using-shell.adoc
deleted file mode 100644
index c8497b12a..000000000
--- a/spring-shell-docs/src/main/asciidoc/using-shell.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-include::using-shell-basics.adoc[]
-
-include::using-shell-commands.adoc[]
-
-include::using-shell-options.adoc[]
-
-include::using-shell-completion.adoc[]
-
-include::using-shell-building.adoc[]
-
-include::using-shell-components.adoc[]
-
-include::using-shell-tui.adoc[]
-
-include::using-shell-customization.adoc[]
-
-include::using-shell-execution.adoc[]
-
-include::using-shell-testing.adoc[]