You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by ah...@apache.org on 2021/01/29 09:56:12 UTC
[isis] branch master updated: ISIS-2508: adds Project Document
Generator docs (README.adoc)
This is an automated email from the ASF dual-hosted git repository.
ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/master by this push:
new 5439012 ISIS-2508: adds Project Document Generator docs (README.adoc)
5439012 is described below
commit 543901216c4609f8b379fb43999b835ea69c0e86
Author: Andi Huber <ah...@apache.org>
AuthorDate: Fri Jan 29 10:55:54 2021 +0100
ISIS-2508: adds Project Document Generator docs (README.adoc)
---
tooling/cli/README.adoc | 74 +++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 72 insertions(+), 2 deletions(-)
diff --git a/tooling/cli/README.adoc b/tooling/cli/README.adoc
index d4f221c..f0d3e3a 100644
--- a/tooling/cli/README.adoc
+++ b/tooling/cli/README.adoc
@@ -18,15 +18,34 @@ java -cp "pathToCLIJar;..." org.apache.isis.tooling.cli.Cli --help
NOTE: TODO: list of commands
+[source]
+.Example Usage (one parameter per line)
+----
+-p=~/git-repo/isis ; <.>
+projdoc ; <.>
+-o=~/git-repo/isis/antora/components/system/modules/generated ; <.>
+----
+
+<.> `-p` the multi-project root
+<.> `projdoc` CLI sub-command selecting the _Project Doc Generator_
+<.> `-o` the output target root for generated _adoc_; we then do walk our way relative from there
+
+
Per default, the current directory is used as the target to perform sub-commands
-in. Default options can be overruled by specifying a configuration file:
+in. Default options can be overruled by specifying a configuration file located at the multi-project root:
[source,yml]
.isis-tooling.yml
----
-# TODO options to be defined
+projectDoc: # <.>
+ option ...
+ option ...
----
+<.> eg. configuration for sub-command `projdoc`
+
+This configuration file is mapped onto the `CLIConfig` bean. Look it up in the java sources for more detailed information.
+
== Install
NOTE: TODO: How to use Maven commands to fetch the dependencies, such that
@@ -45,5 +64,56 @@ https://github.com/apache-isis-committers/isis-nightly#maven[]
</dependency>
----
+== Sub Commands
+
+=== Project Document Generator (projdoc)
+
+Generates the _System Overview_ and the _Document Global Index_ (adoc).
+
+Any class found with magic `{@index}` in its _java-doc_ section at type level, will be included with the _Document Global Index_. Adoc files may refer to the _Document Global Index_ via `xref` or `include` statements using paths like eg. `system:generated:index/applib/Xxx.adoc`.
+
+[source,yml]
+.Configuraton
+----
+projectDoc:
+ description: "These tables summarize all Maven artifacts ..." # <.>
+ licenseHeader: "Licensed to the Apache Software Foundation (ASF) ..." # <.>
+ outputRootFolder: # <.>
+ documentPagesPath: "pages" # <.>
+ documentGlobalIndexPath: "pages/index" # <.>
+ documentGlobalIndexXrefPageIdFormat: "system:generated:index/%s.adoc" # <.>
+ systemOverviewFilename: "system-overview.adoc" # <.>
+ fixOrphandedAdocIncludeStatements: true # <.>
+ namespacePartsSkipCount: 3 # <.>
+ artifactGroups: # <.>
+ Base: org.apache.isis
+ Commons: org.apache.isis.commons.*
+ Core: org.apache.isis.core.*
+ App: org.apache.isis.app.*
+ ...
+----
+
+<.> _System Overview_ head line
+<.> license header to include with each generated adoc file
+<.> the output target root for generated _adoc_; corresponds to command line option `-o` (if empty the current dir is used)
+<.> sub-folder name for _adoc_ pages
+<.> sub-folder name for the _Document Global Index_
+<.> format for include statements via which other _adoc_ files may refer to the Document Global Index
+<.> name of the _System Overview_ (adoc) file
+<.> whether to activate the `OrphanedIncludeStatementFixer`
+<.> 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 artifacts for the system overview, if not specified the natural Maven project hierarchy is reflected as is.
+
+
+The CLI also has an experimental `OrphanedIncludeStatementFixer` that checks orphaned index references in all _adoc_ files and tries to fix them.
+
+==== Limitations
+
+Current limitation with the _Document Global Index_ is, that it can only contain classes
+unique by their simple name, otherwise the `OrphanedIncludeStatementFixer` would not be able to reason about how to fix orphaned references.
+
+The `OrphanedIncludeStatementFixer` also can only detect whether a class that is part of the _Document Global Index_ had been recently moved, but not if the class has been renamed.
+However, moving classes around is a very common refactoring step, at least this one is covered without hassle.
+
\ No newline at end of file