You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2021/03/31 12:54:39 UTC
[isis] 14/20: ISIS-2484: tweaks some config props
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 9bdb92414e97c95dc27d566be1ce517645ab925b
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Mar 29 12:57:46 2021 +0100
ISIS-2484: tweaks some config props
(cherry picked from commit 6740275abea13bc915231affcc37e11b6ec763de)
---
scripts/ci/_adoc-gen-projdoc.sh | 2 +-
.../cli/adoc/modules/tooling-cli/pages/about.adoc | 163 ++++++++++-----------
.../main/java/org/apache/isis/tooling/cli/Cli.java | 4 +-
3 files changed, 77 insertions(+), 92 deletions(-)
diff --git a/scripts/ci/_adoc-gen-projdoc.sh b/scripts/ci/_adoc-gen-projdoc.sh
index 0e9b3e5..37641ce 100644
--- a/scripts/ci/_adoc-gen-projdoc.sh
+++ b/scripts/ci/_adoc-gen-projdoc.sh
@@ -51,7 +51,7 @@ echo ""
if [ -z "${JAVA_CMD}" ]; then
echo "projdoc gen: no java, skipping"
else
- java -jar "${PROJECT_ROOT_PATH}/tooling/cli/target/isis-tooling-cli.jar" -p "${PROJECT_ROOT_PATH}" -r "${OVERVIEW_PATH}" -o "${INDEX_PATH}" $MODE
+ java -jar "${PROJECT_ROOT_PATH}/tooling/cli/target/isis-tooling-cli.jar" -p "${PROJECT_ROOT_PATH}" -w "${OVERVIEW_PATH}" -x "${INDEX_PATH}" $MODE
fi
diff --git a/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc b/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc
index 3418cfe..943acbf 100644
--- a/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc
+++ b/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc
@@ -36,8 +36,10 @@ which (currently) generates the following:
Usage: cli [-hV] [-o=<outputPath>] [-p=<projectRootPath>] [COMMAND]
CLI for the Apache Isis Tooling Ecosystem
-h, --help Show this help message and exit.
- -o, --output=<outputPath>
- path to the output file (default: NONE = write to std.out)
+ -w, --overview=<overviewPath>
+ path to write the overview file (default: NONE = write to std.out)
+ -x, --index=<indexPath>
+ path to write the refguide index files (default: NONE = write to std.out)
-p, --project=<projectRootPath>
path to the (multi-module) project root (default: current dir)
-V, --version Print version information and exit.
@@ -64,8 +66,12 @@ global: # <.>
option ...
command:
overview: # <.>
+ option ...
+ option ...
...
index: # <.>
+ option ...
+ option ...
...
----
@@ -79,69 +85,23 @@ Inspect its https://github.com/apache/isis/blob/master/tooling/cli/src/main/java
== Commands
-All commands accept two parameters:
+All commands accept the following common parameters:
* `-p` indicates the location of the multi-project root `pom.xml`
+
in other words, the root of the git repo.
-* `-o` the output target root for generated _adoc_
-
-These are specified first in the command line.
-The command is then specified, along with any command-specific options.
-
A number of global configuration options can be specified under the `global` entry in the `isis-tooling.yml` file.
[source,yml]
.isis-tooling.yml
----
global:
- outputRootFolder: # <.>
licenseHeader: "Licensed to the Apache Software Foundation (ASF) ..." # <.>
- documentPagesPath: "pages" # <.>
- namespacePartsSkipCount: 3 # <.>
- sections: # <.>
- App: org.apache.isis.app.*
- Mavendeps: org.apache.isis.mavendeps.*
- ...
- Core: org.apache.isis.core.*
- Persistence: org.apache.isis.persistence
- JDO: "org.apache.isis.persistence:isis-persistence-jdo.*"
- JPA: "org.apache.isis.persistence:isis-persistence-jpa.*"
- ...
----
-
-<.> the output target root for generated _adoc_; corresponds to command line option `-o` (if empty the current dir is used)
<.> license header to include with each generated adoc file
-<.> sub-folder name for _adoc_ pages
-<.> how many namespace parts in a _fqn_ one wants to skip, eg. in `org.apache.isis.applib.Xxx` if we skip 3 namespace parts we'll end up with `applib.Xxx`
-<.> Logical grouping of modules for the system overview, but also used to determine which modules to scan for index files.
-+
-If not specified the natural Maven project hierarchy is reflected as is.
-
-The `sections` configuration key is used to group module artifacts into named sections.
-It consists of key:value pairs:
-
-* the key is the section name (eg "App", or "JDO")
-* the value is a pattern that identifies Maven artifacts.
-
-This pattern in turn can be either:
-
-* an exact Maven `groupId`, such as `org.apache.isis.persistence`
-+
-This matches all Maven modules with exactly that `groupId`.
-* a Maven `groupId` with wildcard, such as `org.apache.isis.core.*`
-+
-This matches all Maven modules whose `groupId` pattern matches the groupId.
-* a Maven group and artifact optionally with wildcard, such as `org.apache.isis.persistence:isis-persistence-jdo.*`
-+
-This matches all Maven modules whose `groupId` pattern equals the specified groupId and whose `artifactId` pattern matches the specified `artifactId`.
-
-If a Maven module matches more than one section, then the more specific section (with both group and artifact) is used.
-
-These different types of sections are exploited by the `overview` command, described <<system-overview-overview,below>>.
=== Project documentation (`projdoc`)
@@ -157,17 +117,18 @@ The `projdoc` command is usually invoked as follows:
----
java -jar tooling/cli/target/isis-tooling-cli.jar \
-p . \
- -o antora/components/system/modules/generated \
+ -w core/adoc \
+ -x antora/components/refguide-index \
projdoc
----
where :
-* `-p` and `-o` are the global options for all commands
+* `-p` is a global options for all commands
+* `-w` is the option for the `overview` sub-command, specifying the output root path
+* `-x` is the option for the `index` sub-command
+* `projdoc` selects this sub-command (which simply runs both `overview` and `index` sub-commands)
-* `projdoc` selects this sub-command
-
-There are no command-specific options.
[[projdoc-configuration]]
@@ -181,30 +142,7 @@ However, as it is effectively just the combination of the `overview` and `index`
This command generates the _System Overview_ (`.adoc) page.
-This page summarises the contents of each section (defined by the `global.sections` configuration key), also with a link:https://c4model.com/[C4] diagram showing how the modules relate.
-
-As described <<configuration-file,above>>, sections are defined that either match on a group or on a group and artifact.
-The overview command places these under a level 2 or a level 3 heading respectively.
-By sequencing the sections correctly, this therefore allows a hierarchy to be created.
-
-For example,
-
-[source,yml]
-.isis-tooling.yml
-----
-global:
- ...
- sections:
- ...
- Persistence: org.apache.isis.persistence
- JDO: "org.apache.isis.persistence:isis-persistence-jdo.*"
- JPA: "org.apache.isis.persistence:isis-persistence-jpa.*"
- ...
-----
-
-The `overview` command will render "Persistence" section at level 2 (because its pattern is only for a `groupId`), and then the "JDO" and "JPA" sections underneath at level 3 (because there patterns also include an `artifactId`).
-
-This way, sections can be defined that create a hierarchy.
+This page summarises the contents of each section (defined by the `commands.overview.sections` configuration key), also with a link:https://c4model.com/[C4] diagram showing how the modules relate.
==== Usage
@@ -215,14 +153,14 @@ The `overview` command is usually invoked as follows:
----
java -jar tooling/cli/target/isis-tooling-cli.jar \
-p . \
- -o antora/components/system/modules/generated \
+ -v core/adoc \
overview
----
where :
-* `-p` and `-o` are the global options for all commands
-
+* `-p` is a global options for all commands
+* `-w` is the option for the `overview` sub-command, specifying the output root path
* `overview` selects this sub-command
There are no command-specific options.
@@ -239,11 +177,54 @@ The `overview` command supports a number of command-specific configuration optio
----
commands:
overview:
- description: "These tables summarize all Maven artifacts ..." # <.>
- systemOverviewFilename: "system-overview.adoc" # <.>
+ rootFolder: # <.>
+ pagesPath: "modules/_overview/pages" # <.>
+ systemOverviewFilename: "about.adoc" # <.>
+ description: "These tables summarize all Maven artifacts ..." # <.>
+ sections: # <.>
+ ...
+ Persistence: org.apache.isis.persistence
+ JDO: "org.apache.isis.persistence:isis-persistence-jdo.*"
+ JPA: "org.apache.isis.persistence:isis-persistence-jpa.*"
+ ...
----
-<.> _System Overview_ head line
+<.> the output target root for generated overview _adoc_; corresponds to command line option `-v` (if empty the current dir is used)
+<.> sub-folder name for _adoc_ pages
<.> name of the _System Overview_ (adoc) file
+<.> _System Overview_ summary description text
+<.> Logical grouping of modules for the system overview, but also used to determine which modules to scan for index files.
++
+If not specified the natural Maven project hierarchy is reflected as is.
+This is discussed in more detail below.
+
+The `sections` configuration key is used to group module artifacts into named sections.
+It consists of key:value pairs:
+
+* the key is the section name (eg "App", or "JDO")
+* the value is a pattern that identifies Maven artifacts.
+
+This pattern in turn can be either:
+
+* an exact Maven `groupId`, such as `org.apache.isis.persistence`
++
+This matches all Maven modules with exactly that `groupId`.
+
+* a Maven `groupId` with wildcard, such as `org.apache.isis.core.*`
++
+This matches all Maven modules whose `groupId` pattern matches the groupId.
+
+* a Maven group and artifact optionally with wildcard, such as `org.apache.isis.persistence:isis-persistence-jdo.*`
++
+This matches all Maven modules whose `groupId` pattern equals the specified groupId and whose `artifactId` pattern matches the specified `artifactId`.
+
+If a Maven module matches more than one section, then the more specific section (with both group and artifact) is used.
+
+These different types of sections are exploited by the `overview` command, described <<system-overview-overview,below>>.
+
+Sections that match on a groupID are placed under a level 2 heading, while sections matching on group and artifact are placed under a level 3 heading.
+By sequencing the sections correctly, this therefore allows a hierarchy to be created.
+
+For example, in the config example above the sections defined will render "Persistence" section at level 2 (because its pattern is only for a `groupId`), and then the "JDO" and "JPA" sections underneath at level 3 (because there patterns also include an `artifactId`).
@@ -264,17 +245,16 @@ The `index` command is usually invoked as follows:
----
java -jar tooling/cli/target/isis-tooling-cli.jar \
-p . \
- -o antora/components/system/modules/generated \
+ -x antora/components/refguide-index \
index
----
where :
-* `-p` and `-o` are the global options for all commands
-
+* `-p` is a global options for all commands
+* `-x` is the option for the `index` sub-command, specifying the output root path
* `index` selects this sub-command
-There are no command-specific options.
[[index-configuration]]
@@ -287,13 +267,18 @@ The `index` command supports a number of command-specific configuration options:
----
commands:
index:
+ rootFolder: # <.>
documentGlobalIndexPath: "pages/index" # <.>
documentGlobalIndexXrefPageIdFormat: "system:generated:index/%s.adoc" # <.>
+ namespacePartsSkipCount: 3 # <.>
fixOrphanedAdocIncludeStatements: true # <.>
+
----
+<.> the output target root for generated index _adoc_ files; corresponds to command line option `-x` (if empty the current dir is used)
<.> sub-folder name for the _Document Global Index_
<.> format for include statements via which other _adoc_ files may refer to the Document Global Index
-<.> whether to activate the `OrphanedIncludeStatementFixer`, discussed below.
+<.> how many namespace parts in a _fqn_ one wants to skip, eg. in `org.apache.isis.applib.Xxx` if we skip 3 namespace parts we'll end up with `applib.Xxx`
+<.> whether to activate the `OrphanedIncludeStatementFixer`.
The CLI also has an experimental `OrphanedIncludeStatementFixer` that checks orphaned index references in all _adoc_ files and tries to fix them.
diff --git a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/Cli.java b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/Cli.java
index 1a3b519..d1be26d 100644
--- a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/Cli.java
+++ b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/Cli.java
@@ -49,12 +49,12 @@ class Cli implements Callable<Integer> {
private String projectRootPath;
@Option(
- names = {"-r", "--overview"},
+ names = {"-w", "--overview"},
description = "path to the overview file (default: NONE = write to std.out)")
private String overviewPath;
@Option(
- names = {"-o", "--output"},
+ names = {"-x", "--index"},
description = "path to the index files (default: NONE = write to std.out)")
private String indexPath;