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/02/03 06:58:58 UTC
[isis] branch ISIS-2516 updated: ISIS-2444: adds in docs and
support for combined "projdoc" command
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2516
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/ISIS-2516 by this push:
new adf5e76 ISIS-2444: adds in docs and support for combined "projdoc" command
adf5e76 is described below
commit adf5e76b1f49183d56970690fc7632afad527b1b
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Feb 3 06:58:08 2021 +0000
ISIS-2444: adds in docs and support for combined "projdoc" command
---
.github/workflows/ci-build-site-no-push.yml | 17 ++++-----
preview.sh | 27 ++++----------
.../{_adoc-gen-tooling.sh => _adoc-gen-projdoc.sh} | 4 +-
scripts/ci/_build-site.sh | 12 ++----
.../cli/adoc/modules/tooling-cli/pages/about.adoc | 43 ++++++++++++++++++++--
.../main/java/org/apache/isis/tooling/cli/Cli.java | 4 +-
6 files changed, 63 insertions(+), 44 deletions(-)
diff --git a/.github/workflows/ci-build-site-no-push.yml b/.github/workflows/ci-build-site-no-push.yml
index db0ca1d..b4a132d 100644
--- a/.github/workflows/ci-build-site-no-push.yml
+++ b/.github/workflows/ci-build-site-no-push.yml
@@ -18,7 +18,7 @@ jobs:
PROJECT_ROOT_PATH: ${{ github.workspace }}
CI_SCRIPTS_PATH: ${{ github.workspace }}/scripts/ci
ANTORA_PLAYBOOKS_PATH: ${{ github.workspace }}/antora/playbooks
-
+
# used for printing
TIMESTAMP: ${{ github.event.head_commit.timestamp }}
@@ -28,12 +28,12 @@ jobs:
steps:
- uses: actions/checkout@v2.3.4
-
+
- name: Set up JDK 11
uses: actions/setup-java@v1
with:
java-version: 11
-
+
- name: Setup Script Environment
shell: bash
# we write the more tricky variables to the $SHARED_VARS_FILE using the full power of bash commands
@@ -49,19 +49,19 @@ jobs:
echo REVISION \: $REVISION
cat $SHARED_VARS_FILE
echo ======================================
-
+
- name: Print Node Version
run: node --version
-
+
- name: Install NVM
shell: bash
run: bash $CI_SCRIPTS_PATH/install-nvm.sh
-
+
- name: Install Antora
shell: bash
working-directory: ${{ env.PROJECT_ROOT_PATH }}
- # we install the 'node' modules into the project root under 'node_modules',
+ # we install the 'node' modules into the project root under 'node_modules',
# because we have no privileges to install them globally with -g option
run: npm i @antora/cli@2.3.3 @antora/site-generator-default@2.3.3 @asciidoctor/core@2.2.0 asciidoctor-kroki
@@ -87,8 +87,7 @@ jobs:
run: bash -x $CI_SCRIPTS_PATH/_build-site.sh $ANTORA_PLAYBOOKS_PATH/site.yml
env:
REVISION: ${{ steps.revision.outputs.revision }}
- SKIP_INDEX_GENERATION: true
- SKIP_OVERVIEW_GENERATION: true
+ SKIP_PROJDOC_GENERATION: true
SKIP_EXAMPLES: true
SKIP_CONFIGS: true
SKIP_STALE_EXAMPLE_CHECK: true
diff --git a/preview.sh b/preview.sh
index 374bea9..3cff4c9 100644
--- a/preview.sh
+++ b/preview.sh
@@ -10,20 +10,16 @@ export ANTORA_TARGET_SITE=antora/target/site
# nevertheless, a committer can use this script to easily regenerate the
# index (only) using the -I flag.
#
-export SKIP_INDEX_GENERATION=true
-
PLAYBOOK_FILE=antora/playbooks/site.yml
-while getopts 'ECWIAKSecwiaksxyhf:' opt
+while getopts 'ECPAKSecpaksxyhf:' opt
do
case $opt in
E) export SKIP_EXAMPLES=false
forcing=true ;;
C) export SKIP_CONFIGS=false
forcing=true ;;
- W) export SKIP_OVERVIEW_GENERATION=false
- forcing=true ;;
- I) export SKIP_INDEX_GENERATION=false
+ W) export SKIP_PROJDOC_GENERATION=false
forcing=true ;;
A) export SKIP_ANTORA_GENERATION=false
export SKIP_CLEAR_CACHE=false
@@ -36,8 +32,7 @@ do
e) export SKIP_EXAMPLES=true ;;
c) export SKIP_CONFIGS=true ;;
- w) export SKIP_OVERVIEW_GENERATION=true ;;
- i) export SKIP_INDEX_GENERATION=true ;;
+ p) export SKIP_PROJDOC_GENERATION=true ;;
a) export SKIP_ANTORA_GENERATION=true
export SKIP_CLEAR_CACHE=true
export SKIP_CLEAR_PREVIOUS=true
@@ -55,8 +50,7 @@ do
echo " -e skip examples"
echo " -k skip stale example check"
echo " -c skip config doc generation"
- echo " -w skip system overview generation"
- echo " -i skip index generation"
+ echo " -w skip projdoc generation"
echo " -a skip Antora generation"
echo " -s skip serving generated site"
echo ""
@@ -64,8 +58,7 @@ do
echo " -E force examples"
echo " -K force stale example check"
echo " -C force config doc generation"
- echo " -W force system overview generation"
- echo " -I force index generation"
+ echo " -P force projdoc generation"
echo " -A force Antora generation"
echo " -S force serving generated site"
echo ""
@@ -85,11 +78,8 @@ if [ "$forcing" = "true" ]; then
if [ -z "$SKIP_CONFIGS" ]; then
export SKIP_CONFIGS=true
fi
- if [ -z "$SKIP_OVERVIEW_GENERATION" ]; then
- export SKIP_OVERVIEW_GENERATION=true
- fi
- if [ -z "$SKIP_INDEX_GENERATION" ]; then
- export SKIP_INDEX_GENERATION=true
+ if [ -z "$SKIP_PROJDOC_GENERATION" ]; then
+ export SKIP_PROJDOC_GENERATION=true
fi
if [ -z "$SKIP_ANTORA_GENERATION" ]; then
export SKIP_ANTORA_GENERATION=true
@@ -107,8 +97,7 @@ fi
echo ""
echo "SKIP_EXAMPLES : $SKIP_EXAMPLES"
echo "SKIP_STALE_EXAMPLE_CHECK : $SKIP_STALE_EXAMPLE_CHECK"
-echo "SKIP_OVERVIEW_GENERATION : $SKIP_OVERVIEW_GENERATION"
-echo "SKIP_INDEX_GENERATION : $SKIP_INDEX_GENERATION"
+echo "SKIP_PROJDOC_GENERATION : $SKIP_PROJDOC_GENERATION"
echo "SKIP_CONFIGS : $SKIP_CONFIGS"
echo "SKIP_ANTORA_GENERATION : $SKIP_ANTORA_GENERATION"
echo "SKIP_SERVE : $SKIP_SERVE"
diff --git a/scripts/ci/_adoc-gen-tooling.sh b/scripts/ci/_adoc-gen-projdoc.sh
similarity index 96%
rename from scripts/ci/_adoc-gen-tooling.sh
rename to scripts/ci/_adoc-gen-projdoc.sh
index d128117..eeed2c4 100644
--- a/scripts/ci/_adoc-gen-tooling.sh
+++ b/scripts/ci/_adoc-gen-projdoc.sh
@@ -34,7 +34,7 @@ if [ -z "$REVISION" ]; then
fi
-MODE=$1
+MODE=projdoc
##
@@ -48,7 +48,7 @@ echo ""
# for now meant to run with nightly builds only
if [ -z "${JAVA_CMD}" ]; then
- echo "tooling gen: no java, skipping"
+ echo "projdoc gen: no java, skipping"
else
java -jar "${PROJECT_ROOT_PATH}/tooling/cli/target/isis-tooling-cli.jar" -p "${PROJECT_ROOT_PATH}" -o "${PROJECT_ROOT_PATH}/antora/components/system/modules/generated" $MODE
fi
diff --git a/scripts/ci/_build-site.sh b/scripts/ci/_build-site.sh
index 6412864..4edd030 100644
--- a/scripts/ci/_build-site.sh
+++ b/scripts/ci/_build-site.sh
@@ -40,19 +40,13 @@ else
fi
-if [[ "$SKIP_OVERVIEW_GENERATION" == "true" ]]; then
- echo "skipping overview generation"
+if [[ "$SKIP_PROJDOC_GENERATION" == "true" ]]; then
+ echo "skipping projdoc generation"
else
- bash $SCRIPT_DIR/_adoc-gen-tooling.sh overview
+ bash $SCRIPT_DIR/_adoc-gen-projdoc.sh
fi
-if [[ "$SKIP_INDEX_GENERATION" == "true" ]]; then
- echo "skipping index generation"
-else
- bash $SCRIPT_DIR/_adoc-gen-tooling.sh index
-fi
-
if [[ "$SKIP_ANTORA_GENERATION" == "true" ]]; then
echo "skipping Antora generation ..."
diff --git a/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc b/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc
index e3fad70..11d1307 100644
--- a/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc
+++ b/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc
@@ -42,10 +42,13 @@ CLI for the Apache Isis Tooling Ecosystem
path to the (multi-module) project root (default: current dir)
-V, --version Print version information and exit.
Commands:
+ projdoc Writes all generated (AsciiDoc) to given output.
overview Writes a System Overview document (AsciiDoc) to given output.
index Writes a Global Index (AsciiDoc) to given output.
----
+The "projdoc" command is the usual command to use, as it performs both the "overview" and "index" commands.
+
By default, the current directory is used as the target to perform commands in.
@@ -67,8 +70,8 @@ command:
----
<.> configuration applicable to all commands
-<.> configuration for the "overview" command
-<.> configuration for the "index" command
+<.> configuration for the "overview" command (also used by the "projdoc" command)
+<.> configuration for the "index" command (also used by the "projdoc" command)
TIP: This configuration file is mapped onto the `CLIConfig` bean.
Inspect its https://github.com/apache/isis/blob/master/tooling/cli/src/main/java/org/apache/isis/tooling/cli/CliConfig.java#L31[source code] for more detailed information.
@@ -140,6 +143,40 @@ If a Maven module matches more than one section, then the more specific section
These different types of sections are exploited by the `overview` command, described <<system-overview-overview,below>>.
+=== Project documentation (`projdoc`)
+
+This command generates both a <<system-overview-overview,system overview>> and generates the <<index-index,global index>>, and as such is the command that you will probably want to use most of the time.
+See those two commands for further details.
+
+
+==== Usage
+
+The `projdoc` command is usually invoked as follows:
+
+[source]
+----
+java -jar tooling/cli/target/isis-tooling-cli.jar \
+ -p . \
+ -o antora/components/system/modules/generated \
+ projdoc
+----
+
+where :
+
+* `-p` and `-o` are the global options for all commands
+
+* `projdoc` selects this sub-command
+
+There are no command-specific options.
+
+
+[[projdoc-configuration]]
+==== Configuration
+
+The `projdoc` command has no specific configuration.
+However, as it is effectively just the combination of the `overview` and `index` commands, note that those two commands _do_ have their own configuration settings; see <<overview-configuration,overview configuration>> and <<index-configuration,index configuration>> respectively.
+
+[#system-overview-overview]
=== System Overview (`overview`)
This command generates the _System Overview_ (`.adoc) page.
@@ -170,7 +207,7 @@ The `overview` command will render "Persistence" section at level 2 (because its
This way, sections can be defined that create a hierarchy.
-=== Usage
+==== Usage
The `overview` command is usually invoked as follows:
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 7919c06..dace871 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
@@ -38,9 +38,9 @@ import picocli.CommandLine.Option;
version = "0.1",
description = "CLI for the Apache Isis Tooling Ecosystem",
subcommands = {
+ Cli.ProjectDocCommand.class,
Cli.SystemOverviewCommand.class,
Cli.GlobalIndexCommand.class,
- Cli.ProjectDocCommand.class
})
class Cli implements Callable<Integer> {
@@ -121,7 +121,7 @@ class Cli implements Callable<Integer> {
return 0;
}
}
-
+
@Command(
name = "projdoc",
description = "Writes all generated (AsciiDoc) to given output.")