issue #6295

docs/hop-user-manual/modules/ROOT/pages/hop-tools/hop-doc.adoc

@@ -0,0 +1,158 @@
+////
+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 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.
+////
+:description: Hop Doc generates project documentation
+= Hop Doc
+
+Hop Doc generates documentation for Hop projects in Markdown format with optional HTML output.
+
+== Usage
+
+Generate documentation for a Hop project:
+
+[source,command]
+----
+./hop.bat doc -s /path/to/project -t /path/to/docs [--generate-html] [--remove-markdown]
+----
+
+Or using Hop project variables:
+[source,command]
+----
+./hop.bat run -j my-project doc -t /path/to/docs --generate-html
+----
+
+== Options
+
+[options="header"]
+|===
+|Option |Description |Default
+|-s, --source-folder |Source project folder to document |Required (or use project)
+|-t, --target-folder |Target documentation folder |Required
+|-ip, --include-parameters |Include pipeline/workflow parameters |true
+|-in, --include-notes |Include notes text |false
+|-im, --include-metadata |Include metadata overview |true
+|-n, --project-name |Project name |"Hop" (or HOP_PROJECT_NAME)
+|-gh, --generate-html |Generate HTML versions of all docs |false
+|-rmmd, --remove-markdown |Remove .md files after HTML generation |false
+|===
+
+== Examples
+
+=== Basic Documentation
+
+Generate Markdown documentation only:
+
+[tabs]
+====
+Windows::
++
+--
+[source,shell]
+----
+./hop.bat doc -s "C:\Projects\my-hop-project" -t "C:\yourLocation\docs"
+----
+
+Linux/macOS::
++
+--
+[source,shell]
+----
+./hop.sh doc -s ~/projects/my-hop-project -t ~/docs
+----
+====
+
+=== HTML Documentation
+
+Generate HTML + remove Markdown source:
+
+[tabs]
+====
+Windows::
++
+--
+[source,shell]
+----
+./hop.bat doc -s "C:\Projects\my-hop-project" -t "C:\yourLocation\docs" --generate-html --remove-markdown
+----
+
+Generates:
+[source]
+----
+C:\docs\
+├── index.html (project TOC)
+├── pipelines\
+│   └── my-pipeline.html
+├── workflows\
+│   └── my-workflow.html
+└── assets\
+    ├── styles.css
+    └── images\
+----
+
+Linux/macOS::
++
+--
+[source,shell]
+----
+./hop.sh doc -s ~/projects/my-hop-project -t ~/docs --generate-html --remove-markdown
+----
+====
+
+=== Using Hop Project Context
+
+[source,shell]
+----
+./hop.bat run -j IT-mongo doc -t "C:\yourLocation\docs" --generate-html
+----
+
+Uses `HOP_PROJECT_HOME` and `HOP_PROJECT_NAME` automatically.
+
+== Workflow Action Usage
+
+Add "Documentation" action to any Hop workflow:
+
+1. Drag **Documentation** action from Utility category
+2. Set **Target folder** (`C:\yourLocation\docs`)
+3. Optional: Check **Generate HTML**
+4. Optional: Check **Remove markdown** (only when Generate HTML enabled)
+5. Configure content options:
+   - ☑ **Include parameters** (optional)
+   - ☑ **Include metadata** (optional)
+   - ☐ **Include notes** (optional)
+
+== Generated Structure
+
+docs/
+├── index.html (Table of Contents)
+├── pipelines/ (all .hpl files)
+│ ├── pipeline1.html
+│ └── subfolder/
+│ └── pipeline2.html
+├── workflows/ (all .hwf files)
+│ └── workflow1.html
+├── metadata/ (metadata overview)
+└── assets/
+├── styles.css
+└── images/
+
+== Notes
+
+* `--remove-markdown` is **automatically disabled** if `--generate-html` is false
+* HTML output includes custom CSS styling and responsive images
+* All links in `index.html` automatically point to `.html` files
+* Supports nested folders and metadata documentation
+* Uses CommonMark for Markdown → HTML conversion

docs/hop-user-manual/modules/ROOT/pages/hop-tools/index.adoc

@@ -28,4 +28,5 @@ This page provides an overview of the tools that are available in the platform.
 * xref:hop-run/index.adoc[Hop Run]
 * xref:hop-tools/hop-search.adoc[Hop Search]
 * xref:hop-tools/hop-import.adoc[Hop Import]
+* xref:hop-tools/hop-doc.adoc[Hop Documentation]
 * xref:hop-server/index.adoc[Hop Server]

docs/hop-user-manual/modules/ROOT/pages/workflow/actions/documentation.adoc

@@ -29,8 +29,11 @@ This action builds documentation of your Hop files or project.
 * The target folder in which you want your project documentation to end up in.
 * Include notes?
 * Include parameters?
+* Include metadata?
+* Generate HTML?
+* Remove MarkDown after HTML is generated?
 
-== Generating HTML
+== Generating HTML from MarkDown
 
 The links from the index are currently set to the .md.html files.
 I ran the following command in the target folder to generate the HTML files:

plugins/misc/documentation/pom.xml

@@ -29,4 +29,28 @@
     <packaging>jar</packaging>
     <name>Hop Plugins Miscellaneous Documentation</name>
 
+    <properties>
+        <commonmark.version>0.27.0</commonmark.version>
+    </properties>
+
+    <dependencyManagement>
+        <dependencies>
+            <dependency>
+                <groupId>org.apache.hop</groupId>
+                <artifactId>hop-libs</artifactId>
+                <version>${project.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.commonmark</groupId>
+            <artifactId>commonmark</artifactId>
+            <version>${commonmark.version}</version>
+        </dependency>
+    </dependencies>
+
 </project>

plugins/misc/documentation/src/assembly/assembly.xml

@@ -47,5 +47,17 @@
             </includes>
             <outputDirectory>plugins/misc/documentation</outputDirectory>
         </dependencySet>
+        <dependencySet>
+            <scope>runtime</scope>
+            <excludes>
+                <exclude>commons-codec:*</exclude>
+                <exclude>commons-logging:*</exclude>
+                <exclude>org.slf4j:*</exclude>
+                <exclude>org.apache.httpcomponents:*</exclude>
+            </excludes>
+            <outputDirectory>plugins/misc/documentation/lib</outputDirectory>
+            <useTransitiveDependencies>true</useTransitiveDependencies>
+            <useProjectArtifact>false</useProjectArtifact>
+        </dependencySet>
     </dependencySets>
 </assembly>

plugins/misc/documentation/src/main/java/org/apache/hop/documentation/ActionDoc.java

@@ -83,13 +83,34 @@ public class ActionDoc extends ActionBase implements Cloneable, IAction {
   @HopMetadataProperty
   private boolean includingMetadata = true;
 
+  @GuiWidgetElement(
+      id = "1040-action-doc-dialog-generate-Html",
+      parentId = GUI_WIDGETS_PARENT_ID,
+      type = GuiElementType.CHECKBOX,
+      variables = false,
+      label = "i18n::ActionDoc.generateHtml.Label")
+  @HopMetadataProperty
+  private boolean generateHtml = true;
+
+  @GuiWidgetElement(
+      id = "1050-action-doc-dialog-remove-markdown",
+      parentId = GUI_WIDGETS_PARENT_ID,
+      type = GuiElementType.CHECKBOX,
+      variables = false,
+      label = "i18n:ActionDoc.RemoveMarkdown.Label")
+  @HopMetadataProperty
+  private boolean removeMarkdown = false;
+
   public ActionDoc() {}
 
   public ActionDoc(ActionDoc other) {
     super(other.getName(), other.getDescription(), other.getPluginId());
     this.targetParentFolder = other.targetParentFolder;
     this.includingNotes = other.includingNotes;
     this.includingParameters = other.includingParameters;
+    this.includingMetadata = other.includingMetadata;
+    this.generateHtml = other.generateHtml;
+    this.removeMarkdown = other.removeMarkdown;
   }
 
   @Override
@@ -107,6 +128,12 @@ public ActionDoc clone() {
   @Override
   public Result execute(Result prevResult, int nr) {
 
+    // SAFETY CHECK: Disable removeMarkdown if generateHtml=false
+    if (removeMarkdown && !generateHtml) {
+      getLogChannel().logBasic("Remove Markdown disabled - Generate HTML not selected");
+      removeMarkdown = false;
+    }
+
     MultiMetadataProvider provider;
     if (getMetadataProvider() instanceof MultiMetadataProvider) {
       provider = (MultiMetadataProvider) getMetadataProvider();
@@ -124,7 +151,9 @@ public Result execute(Result prevResult, int nr) {
             resolve(targetParentFolder),
             includingParameters,
             includingNotes,
-            includingMetadata);
+            includingMetadata,
+            generateHtml,
+            removeMarkdown);
     docBuilder.buildDocumentation(prevResult);
     return prevResult;
   }