<commit_before>= Tooling - CLI
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Command Line Interface for the _Apache Isis Tooling_ ecosystem. 

WARNING: This is work-in-progress. Regard the following text as an early draft.

== Usage

Use the included help command to see a list of available commands.

[source]
.calling for help
----
java -cp "pathToCLIJar;..." org.apache.isis.tooling.cli.Cli --help 
----

NOTE: TODO: list of commands

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: 

[source,yml]
.isis-tooling.yml
----
# TODO options to be defined
----

== Install

NOTE: TODO: How to use Maven commands to fetch the dependencies, such that
the jar artifacts can be used from command line with little hassle
as possible? 

Use Maven and our snapshot repository for a preview:
https://github.com/apache-isis-committers/isis-nightly#maven[]

[source,xml]
----
<dependency>
    <groupId>org.apache.isis.tooling</groupId>
    <artifactId>isis-tooling-cli</artifactId>
    <version>2.0.0-???</version>
</dependency>
----


 <commit_msg>ISIS-2508: adds Project Document Generator docs (README.adoc)<commit_after>= Tooling - CLI
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Command Line Interface for the _Apache Isis Tooling_ ecosystem. 

WARNING: This is work-in-progress. Regard the following text as an early draft.

== Usage

Use the included help command to see a list of available commands.

[source]
.calling for help
----
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 located at the multi-project root: 

[source,yml]
.isis-tooling.yml
----
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
the jar artifacts can be used from command line with little hassle
as possible? 

Use Maven and our snapshot repository for a preview:
https://github.com/apache-isis-committers/isis-nightly#maven[]

[source,xml]
----
<dependency>
    <groupId>org.apache.isis.tooling</groupId>
    <artifactId>isis-tooling-cli</artifactId>
    <version>2.0.0-???</version>
</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.


 
{'fraction_non_alphanumeric': 0.08350277890741493, 'fraction_numerical': 0.0027111291853056797, 'mean_word_length': 3.096612992781788, 'pattern_counts': {'":': 0, '<': 47, '<?xml version=': 0, '>': 47, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 16, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '887173', 'n_tokens_mistral': 2019, 'n_tokens_neox': 1904, 'n_words': 868}