Repository: kroxylicious/kroxylicious
Pull request #1921: Rearrange `docs/` to support multiple guides
Author: login: tombentley
Labels: name: documentation
description: Improvements or additions to documentation
Created: 2025-03-11T21:45:16Z | Merged: 2025-03-13T21:24:05Z

### Type of change

- Documentation

### Description

This PR rearranges the `docs` directory to support the generation of multiple guides. No new guides are added in this PR.

### Additional Context

Because we're intending to have a guide specifically for the operator.




Diff:
diff --git a/.github/workflows/asciidoctor-ghpages.yaml b/.github/workflows/asciidoctor-ghpages.yaml
index 3b342bf895..1863cea932 100644
--- a/.github/workflows/asciidoctor-ghpages.yaml
+++ b/.github/workflows/asciidoctor-ghpages.yaml
@@ -37,6 +37,6 @@ jobs:
       - name: asciidoctor-ghpages
         uses: manoelcampos/asciidoctor-ghpages-action@v2
         with:
-          source_dir: docs/
+          source_dir: docs/kroxylicous-proxy
           asciidoctor_params: "--require asciidoctor-diagram --attribute=sectlinks --attribute=sectanchors"
           post_build: 'find . -name "*.svg" -exec git add -f {} \;'
diff --git a/docs/README.md b/docs/README.md
index f96fab7a68..605afd3d48 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -19,35 +19,38 @@ US (global) English is used throughout.
 
 ## Kroxylicious guide
 
-The Kroxylicious documentation is organized into a single **Kroxylicious** guide.
-The content for the guide is encapsulated in a main index file:
+The Kroxylicious documentation is organized into specific **Kroxylicious** guides.
 
-- [Index file](index.adoc)
+The content for the guide to the proxy is encapsulated in a main index file:
+
+- [kroxylicious-proxy.adoc](kroxylicious-proxy/kroxylicious-proxy.adoc)
 
 ## Documentation folder structure
 
 The index file is used to build the documentation.
 Documentation folders contain the content that's incorporated into the main source files.
 An assembly is like a sub-section or chapter in a book.
-A module contain a procedure (`proc-`), concepts (`con-`), or reference (`ref-`) content.
+A module contains a procedure (`proc-`), concepts (`con-`), or reference (`ref-`) content.
 
 **Documentation folders**
-| Folder                   | Description                                          |
-| --------------           | -------------------------------------------------    |
-| `assemblies/`            | Assemblies (chapters) group related content          |
-| `modules/`               | Modules provide content for assemblies               |
-| `_assets/`               | Content common to all doc files                      |
-| `shared/attributes.adoc` | Global book attributes                               |
+
+| Folder                   | Description                                 |
+|--------------------------|---------------------------------------------|
+| `assemblies/`            | Assemblies (chapters) group related content |
+| `modules/`               | Modules provide content for assemblies      |
+| `_assets/`               | Content common to all doc files             |
+| `shared/attributes.adoc` | Global book attributes                      |
+| `kroxylicious-proxy/`    | The Kroxylicious Proxy guide                |
 
 ## Generating the guide
 
 To generate the guide in HTML, run the following Maven command:
 
 ```shell
-mvn org.asciidoctor:asciidoctor-maven-plugin:process-asciidoc@convert-to-html
+mvn org.asciidoctor:asciidoctor-maven-plugin:process-asciidoc@convert-kroxylicious-proxy-to-html
 ```
 
-The HTML is output to `target/html/index.html`. 
+The HTML is output to `target/kroxylicious-proxy/html/index.html`. 
 
 ## Contributing to the documentation
 
diff --git a/docs/assemblies/assembly-built-in-filters.adoc b/docs/assemblies/assembly-built-in-filters.adoc
index f38afa37bc..503d54ed07 100644
--- a/docs/assemblies/assembly-built-in-filters.adoc
+++ b/docs/assemblies/assembly-built-in-filters.adoc
@@ -1,6 +1,6 @@
 // file included in the following:
 //
-// index.adoc
+// kroxylicious-proxy.adoc
 
 [id='assembly-built-in-filters-{context}']
 = Built-in filters
diff --git a/docs/assemblies/assembly-monitoring-proxy.adoc b/docs/assemblies/assembly-monitoring-proxy.adoc
index 5c78f623a1..26c7b16b10 100644
--- a/docs/assemblies/assembly-monitoring-proxy.adoc
+++ b/docs/assemblies/assembly-monitoring-proxy.adoc
@@ -1,6 +1,6 @@
 // file included in the following:
 //
-// index.adoc
+// kroxylicious-proxy.adoc
 
 [id='con-operating-{context}']
 = Monitoring proxies
diff --git a/docs/assemblies/assembly-overview.adoc b/docs/assemblies/assembly-overview.adoc
index b503fd28ae..04e02126d7 100644
--- a/docs/assemblies/assembly-overview.adoc
+++ b/docs/assemblies/assembly-overview.adoc
@@ -1,6 +1,6 @@
 // file included in the following:
 //
-// index.adoc
+// kroxylicious-proxy.adoc
 
 [id='assembly-overview-{context}']
 = Kroxylicious overview
diff --git a/docs/kroxylicious-proxy/_assets b/docs/kroxylicious-proxy/_assets
new file mode 120000
index 0000000000..f6c9582d4c
--- /dev/null
+++ b/docs/kroxylicious-proxy/_assets
@@ -0,0 +1 @@
+../_assets
\ No newline at end of file
diff --git a/docs/kroxylicious-proxy/assemblies b/docs/kroxylicious-proxy/assemblies
new file mode 120000
index 0000000000..ff41b88e39
--- /dev/null
+++ b/docs/kroxylicious-proxy/assemblies
@@ -0,0 +1 @@
+../assemblies
\ No newline at end of file
diff --git a/docs/index.adoc b/docs/kroxylicious-proxy/kroxylicious-proxy.adoc
similarity index 100%
rename from docs/index.adoc
rename to docs/kroxylicious-proxy/kroxylicious-proxy.adoc
diff --git a/docs/kroxylicious-proxy/modules b/docs/kroxylicious-proxy/modules
new file mode 120000
index 0000000000..464b823aca
--- /dev/null
+++ b/docs/kroxylicious-proxy/modules
@@ -0,0 +1 @@
+../modules
\ No newline at end of file
diff --git a/docs/modules/con-community-filters.adoc b/docs/modules/con-community-filters.adoc
index d0912a979a..0584f64be9 100644
--- a/docs/modules/con-community-filters.adoc
+++ b/docs/modules/con-community-filters.adoc
@@ -1,6 +1,6 @@
 // file included in the following:
 //
-// index.adoc
+// kroxylicious-proxy.adoc
 
 [id='con-community-filters-{context}']
 = Community filters
diff --git a/docs/modules/con-custom-filters.adoc b/docs/modules/con-custom-filters.adoc
index 4e2140093e..b5de100cef 100644
--- a/docs/modules/con-custom-filters.adoc
+++ b/docs/modules/con-custom-filters.adoc
@@ -1,6 +1,6 @@
 // Assembly included in the following:
 //
-// index.adoc
+// kroxylicious-proxy.adoc
 
 [id='con-custom-filters-{context}']
 = Custom filters
diff --git a/pom.xml b/pom.xml
index 5c71475858..56483a872f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -816,7 +816,7 @@
                 </dependencies>
                 <executions>
                     <execution>
-                        <id>convert-to-html</id>
+                        <id>convert-kroxylicious-proxy-to-html</id>
                         <goals>
                             <goal>process-asciidoc</goal>
                         </goals>
@@ -824,7 +824,10 @@
                             <requires>
                                 <require>asciidoctor-diagram</require>
                             </requires>
-                            <outputDirectory>${project.build.directory}/html</outputDirectory>
+                            <sourceDirectory>docs/kroxylicious-proxy</sourceDirectory>
+                            <sourceDocumentName>kroxylicious-proxy.adoc</sourceDocumentName>
+                            <outputDirectory>${project.build.directory}/kroxylicious-proxy/html</outputDirectory>
+                            <outputFile>index.html</outputFile>
                             <attributes>
                                 <source-highlighter>coderay</source-highlighter>
                                 <imagesdir>./images</imagesdir>
@@ -834,8 +837,6 @@
                                 <attribute>revdate!</attribute>
                                 <attribute>revremark!</attribute>
                             </attributes>
-                            <sourceDirectory>docs</sourceDirectory>
-                            <sourceDocumentName>index.adoc</sourceDocumentName>
                         </configuration>
                     </execution>
                 </executions>


Reviews:
user: login: k-wall
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-12T16:20:55Z
user: login: PaulRMellor
body: Thanks, Tom
So this sets us up with the structure for the first guide.
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-13T08:36:46Z
user: login: k-wall
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-13T17:55:07Z

Review comments:
diff_hunk: @@ -32,22 +33,24 @@ An assembly is like a sub-section or chapter in a book.
 A module contain a procedure (`proc-`), concepts (`con-`), or reference (`ref-`) content.
path: docs/README.md
user: login: k-wall
body: ```suggestion
A module contains a procedure (`proc-`), concepts (`con-`), or reference (`ref-`) content.
```
created_at: 2025-03-12T16:20:55Z
author_association: MEMBER
diff_hunk: @@ -19,10 +19,11 @@ US (global) English is used throughout.
 
 ## Kroxylicious guide
 
-The Kroxylicious documentation is organized into a single **Kroxylicious** guide.
-The content for the guide is encapsulated in a main index file:
+The Kroxylicious documentation is organized into a several **Kroxylicious** guides.
path: docs/README.md
user: login: PaulRMellor
body: ```suggestion
The Kroxylicious documentation is organized into specific **Kroxylicious** guides.
```
created_at: 2025-03-13T08:32:48Z
author_association: CONTRIBUTOR

PR comments:
user: login: k-wall
created_at: 2025-03-12T16:32:13Z
body: I don't think I understand the direction this PR is going.  I agree that multiple guides is where we want to end up.  I think we we will want to share some content between the Kroxylicious proxy and Kroxylicious for Kubernetes guides.  I don't see how the symlinks is helps that. 


author_association: MEMBER
user: login: tombentley
created_at: 2025-03-12T17:35:49Z
body: I'm following the same pattern used in Strimzi, where each guide gets its own directory, but modules and artifacts are shared. The symlinks avoid mean the includes don't need to use ..
author_association: MEMBER
user: login: sonarqubecloud[bot]
created_at: 2025-03-13T21:24:05Z
body: ## [![Quality Gate Passed](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/checks/QualityGateBadge/qg-passed-20px.png 'Quality Gate Passed')](https://sonarcloud.io/dashboard?id=kroxylicious_kroxylicious&pullRequest=1921) **Quality Gate passed**  
Issues  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 New issues](https://sonarcloud.io/project/issues?id=kroxylicious_kroxylicious&pullRequest=1921&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/accepted-16px.png '') [0 Accepted issues](https://sonarcloud.io/project/issues?id=kroxylicious_kroxylicious&pullRequest=1921&issueStatuses=ACCEPTED)

Measures  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 Security Hotspots](https://sonarcloud.io/project/security_hotspots?id=kroxylicious_kroxylicious&pullRequest=1921&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Coverage on New Code](https://sonarcloud.io/component_measures?id=kroxylicious_kroxylicious&pullRequest=1921&metric=new_coverage&view=list)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Duplication on New Code](https://sonarcloud.io/component_measures?id=kroxylicious_kroxylicious&pullRequest=1921&metric=new_duplicated_lines_density&view=list)  
  
[See analysis details on SonarQube Cloud](https://sonarcloud.io/dashboard?id=kroxylicious_kroxylicious&pullRequest=1921)


author_association: NONE