hansva commented on code in PR #9327:
URL: https://github.com/apache/hop/pull/9327#discussion_r4491298791


##########
docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-driver.adoc:
##########
@@ -0,0 +1,126 @@
+////
+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.
+////
+[[HopDriver]]
+:description: hop driver lists the JDBC drivers Hop can download and installs 
them from Maven Central or another Maven repository.
+
+= hop driver
+
+`hop driver` lists the JDBC drivers that Hop knows how to download, and 
installs them with the libraries they need.
+
+The database plugins declare which driver they use.
+`hop driver` reads that list, so it only knows the database types installed in 
your Hop.
+
+See xref:database/databases.adoc#_adding_jdbc_drivers[Adding JDBC drivers] for 
the other ways to get a driver: the *Download driver* button in the connection 
editor, and the `HOP_DRIVERS_DOWNLOAD` variable of the Docker image.
+
+[source,bash]
+----
+hop driver list
+hop driver install <driver-id> [options]
+----
+
+== hop driver list
+
+Lists every downloadable driver, with its license category and whether it is 
installed.
+
+[source,bash]
+----
+$ ./hop driver list
+JDBC drivers declared by the database plugins
+Scanned folders: [/opt/hop/lib/jdbc]
+
+ID           DATABASE                   LIC   INSTALLED  ARTIFACT:VERSION
+----         --------                   ---   ---------  ----------------
+derby        Apache Derby               A     yes        
org.apache.derby:derbyclient:10.17.1.0

Review Comment:
   Please leave the driver versions out of this sample. We change them in the 
POM and in `DriverDownload.defaultVersion` with every driver upgrade, and a 
page that repeats them is out of date after the next one. A placeholder keeps 
the sample correct:
   
   ```
   derby        Apache Derby               A     yes        
org.apache.derby:derbyclient:<version>
   duckdb       DuckDB                     A     no         
org.duckdb:duckdb_jdbc:<version>
   ...
   ```
   
   The same goes for the other rows. On line 82, `--driver-version <version>` 
would also be safer than `3.4.1`.



##########
docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-driver.adoc:
##########
@@ -0,0 +1,126 @@
+////
+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.
+////
+[[HopDriver]]
+:description: hop driver lists the JDBC drivers Hop can download and installs 
them from Maven Central or another Maven repository.
+
+= hop driver
+
+`hop driver` lists the JDBC drivers that Hop knows how to download, and 
installs them with the libraries they need.
+
+The database plugins declare which driver they use.
+`hop driver` reads that list, so it only knows the database types installed in 
your Hop.
+
+See xref:database/databases.adoc#_adding_jdbc_drivers[Adding JDBC drivers] for 
the other ways to get a driver: the *Download driver* button in the connection 
editor, and the `HOP_DRIVERS_DOWNLOAD` variable of the Docker image.
+
+[source,bash]
+----
+hop driver list
+hop driver install <driver-id> [options]
+----
+
+== hop driver list
+
+Lists every downloadable driver, with its license category and whether it is 
installed.
+
+[source,bash]
+----
+$ ./hop driver list
+JDBC drivers declared by the database plugins
+Scanned folders: [/opt/hop/lib/jdbc]
+
+ID           DATABASE                   LIC   INSTALLED  ARTIFACT:VERSION
+----         --------                   ---   ---------  ----------------
+derby        Apache Derby               A     yes        
org.apache.derby:derbyclient:10.17.1.0
+duckdb       DuckDB                     A     no         
org.duckdb:duckdb_jdbc:1.5.6.0
+mysql        MySQL                      X     no         
com.mysql:mysql-connector-j:9.7.0
+oracle       Oracle                     X     no         
com.oracle.database.jdbc:ojdbc11:23.26.2.0.0
+postgresql   PostgreSQL                 A     yes        
org.postgresql:postgresql:42.7.14
+...
+----
+
+[options="header", cols="1,3"]
+|===
+|Column|Description
+|`ID`|The id to pass to `hop driver install`.
+|`DATABASE`|The database type.
+|`LIC`|The ASF license category of the driver. `A` and `B` drivers may ship 
with Hop. `X` drivers are restricted, for example proprietary, GPL or LGPL 
licensed. Hop never ships them, and only downloads them when you accept the 
vendor's license.
+|`INSTALLED`|`yes` when a jar of the driver, in any version, is in one of the 
scanned folders.
+|`ARTIFACT:VERSION`|The Maven artifact and the version that `hop driver 
install` downloads by default.
+|===
+
+The scanned folders are the entries of `HOP_SHARED_JDBC_FOLDERS`, or 
`lib/jdbc` when that variable is not set.
+
+[options="header", cols="1,3"]
+|===
+|Option|Description
+|`--target <folder>`|Only check this folder for installed drivers.
+|===
+
+== hop driver install
+
+Downloads a driver, with the libraries it depends on, and copies the jars into 
a JDBC folder.
+Restart Hop, Hop Server or the worker afterwards so the driver is loaded.
+
+[source,bash]
+----
+hop driver install postgresql
+hop driver install oracle --accept-license
+hop driver install mariadb --accept-license --driver-version 3.4.1
+hop driver install duckdb --target /opt/hop-drivers
+----
+
+[options="header", cols="1,3"]
+|===
+|Option|Description
+|`<driver-id>`|The `ID` of the driver in `hop driver list`.
+|`--accept-license`|Accept the vendor's license. Required for restricted 
(`LIC` `X`) drivers. Without it, Hop prints the license and the vendor's links 
and installs nothing.
+|`--driver-version <version>`|The version to install. By default, the version 
shown by `hop driver list`.
+|`--force`|Download and install the driver again, also when the same version 
is already installed.
+|`--repo <url>`|The Maven repository to download from instead of Maven 
Central, for example an internal mirror. A driver that is published in another 
repository, such as MonetDB, is also looked up there.
+|`--target <folder>`|The folder to install into. By default, the first entry 
of `HOP_SHARED_JDBC_FOLDERS` that is not `lib/jdbc`. Without such an entry, 
`lib/jdbc`.
+|===
+
+The default target keeps downloaded drivers out of Hop's own `lib/jdbc` folder 
as soon as `HOP_SHARED_JDBC_FOLDERS` names another folder.
+See xref:database/databases.adoc#_adding_a_driver_manually[Adding a driver 
manually] for `HOP_SHARED_JDBC_FOLDERS`.
+
+Some drivers need extra jars at runtime.
+`hop driver install` downloads them too, and installs a missing one when the 
driver itself is already there.
+For example, the Oracle driver gets `oraclepki`, which connections with an 
Oracle Wallet need.
+
+=== Drivers that are already installed
+
+When the same version is already in the target folder, `hop driver install` 
only says so.
+Use `--force` to download it again.
+
+Hop only looks for installed drivers in the scanned folders: the entries of 
`HOP_SHARED_JDBC_FOLDERS`, or `lib/jdbc`.
+A `--target` folder outside them is downloaded into again on every install.
+
+When the driver is also in another scanned folder, for example the bundled one 
in `lib/jdbc`, Hop prints a note and leaves that copy in place.
+Remove the copy you don't want, so that the driver is not loaded twice.
+
+Downloaded files are cached in `.hop/driver-cache` in your home folder.
+
+=== Exit codes
+
+[options="header", cols="1,3"]
+|===
+|Code|Meaning
+|`0`|The driver is installed, or was already installed.
+|`2`|The driver is restricted and `--accept-license` was not given.
+|`3`|No database type in this Hop uses that id.
+|`4`|The database type exists, but declares no driver that can be downloaded. 
Download the driver from the vendor and copy it into the JDBC folder.

Review Comment:
   One code is missing: when the download or the install fails (no network, a 
version that doesn't exist, a folder that can't be written), 
`DriverInstallCommand` throws an exception and `hop` ends with picocli's 
default code `1`. Could you add a row?
   
   ```
   |`1`|The download or the install failed. The error is printed.
   ```



##########
docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-export.adoc:
##########
@@ -0,0 +1,106 @@
+////
+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.
+////
+[[HopExport]]
+:description: hop export writes pipeline and workflow diagrams to SVG or 
Mermaid files, for one file or a whole folder.
+
+= hop export
+
+`hop export` writes the diagram of a pipeline or a workflow to a file, in SVG 
or Mermaid format.
+It exports one file, or every pipeline and workflow in a folder.
+
+It uses the same exporters as *File > Export diagram* in Hop Gui, so you can 
create the diagrams from a script or a build.
+The installation also has `hop-export.sh` and `hop-export.bat`, which run the 
same command.
+
+[source,bash]
+----
+# One file
+hop export -f pipelines/load-orders.hpl -o diagrams/load-orders.svg
+
+# One file as Mermaid
+hop export -f workflows/main.hwf --format mermaid -o diagrams/main.mmd
+
+# Every pipeline and workflow in a folder and its subfolders
+hop export -s /path/to/project -t /path/to/diagrams --recursive
+
+# The formats this installation can write
+hop export --list-exporters
+----
+
+== Options
+
+[options="header", cols="1,3"]
+|===
+|Option|Description
+|`-f`, `--file <file>`|The pipeline (`.hpl`) or workflow (`.hwf`) to export.
+|`-o`, `--output-file <file>`|The file to write, for `-f`. By default, the 
name of the exported file with the extension of the format (`.svg` or `.mmd`), 
in the same folder.
+|`--format <format>`|`svg` or `mermaid`, in upper or lower case. Without it, 
an `-o` file that ends in `.mmd` is written as Mermaid, and one that ends in 
`.svg` as SVG. Without `--format` and `-o`, the format is SVG.
+|`-s`, `--source-folder <folder>`|The folder to export every pipeline and 
workflow from.
+|`-t`, `--target-folder <folder>`|The folder to write the diagrams to, for 
`-s`. Required with `-s`. See <<_exporting_a_folder,Exporting a folder>>.
+|`-r`, `--recursive`|With `-s`, also export the subfolders.
+|`-m`, `--magnification <factor>`|Scale an SVG diagram, for example `2` for 
twice the size. The default is `1.0`. Mermaid diagrams are not scaled.
+|`-in`, `--include-notes`|Notes are included by default. Use `-in=false` to 
leave them out of a Mermaid diagram. Giving `-in` without a value also leaves 
them out. SVG diagrams always show the notes.
+|`--list-exporters`|List the exporters in this installation, with their format 
and file extension.
+|`-j`, `--project <name>`|Enable a project first, so that variables such as 
`+${PROJECT_HOME}+` can be used in the file names.
+|`-e`, `--environment <name>`|Enable an environment, and its project, first.
+|===
+
+The project options are the same as for xref:hop-run/index.adoc[hop run]:
+
+[source,bash]
+----
+hop export -j my-project -f '${PROJECT_HOME}/pipelines/load-orders.hpl' -o 
/tmp/load-orders.svg
+----
+
+Run `hop export --help` for the full list, which also has `-pl`, 
`--environments` and the other options of the xref:hop-tools/hop.adoc[hop] 
command.
+
+== Formats
+
+Hop has an SVG and a Mermaid exporter for both pipelines and workflows.
+Plugins can add more; `--list-exporters` shows what your installation has.
+
+[source,bash]
+----
+$ ./hop export --list-exporters
+Available Diagram Exporters (4):
+  ID: pipeline-mermaid
+    Name: Pipeline Mermaid Exporter
+    Format: MERMAID
+    Extension: .mmd
+    Description: Exports a pipeline diagram to Mermaid flowchart (.mmd)
+
+  ID: pipeline-svg
+    Name: Pipeline SVG Exporter
+...
+----
+
+* *SVG* draws the diagram as it looks in Hop Gui, with the transform and 
action icons and the notes.
+* *Mermaid* writes a text flowchart (`.mmd`) with a node per transform or 
action and an arrow per hop. You can keep it next to the project in version 
control, or paste it into a page that renders Mermaid.
+
+== Exporting a folder
+
+With `-s`, `hop export` exports every `.hpl` and `.hwf` file in the folder, 
and with `-r` in its subfolders too.
+Each diagram is written under `-t` with the same relative path, for example 
`pipelines/load-orders.hpl` becomes `pipelines/load-orders.svg`.
+
+* `-t` must be an existing folder. With `-r`, its subfolders must exist as 
well.
+* The export stops at the first file it can't export, for example a diagram 
whose folder is missing under `-t`, or a file that is not valid XML. The 
diagrams written before it stay.
+* A pipeline and a workflow with the same name in the same folder are written 
to the same file, so only the last one is kept.
+
+At the end, the command logs how many diagrams it exported.
+
+== Exit codes
+
+`hop export` ends with `0` when the export is done, and with `1` when it 
fails, for example when the source folder doesn't exist or a diagram can't be 
written.

Review Comment:
   This is right for `hop export`, but not for the `hop-export.sh` / 
`hop-export.bat` scripts mentioned at the top of the page. They run 
`DiagramExportCommand.main()`, which ends with other codes:
   
   - `0`: the export is done
   - `1`: after `--help`
   - `2`: the export fails, for example when the source folder doesn't exist
   - `9`: an option is not valid
   
   A script that checks the exit code of `hop-export.sh` would not see the `1` 
it expects from this page. Could you add the codes of the scripts, or say that 
they differ from `hop export`?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to