Rearrange docs/ to support multiple guides (kroxylicious#1921)

tombentley · PaulRMellor · k-wall · web-flow · commit 885c643a2a62 · 2025-03-13T21:24:05.000Z
Follow the pattern used by Strimzi.

Signed-off-by: Tom Bentley &lt;tbentley@redhat.com&gt;
Co-authored-by: PaulRMellor &lt;47596553+PaulRMellor@users.noreply.github.com&gt;
Co-authored-by: Keith Wall &lt;kwall@redhat.com&gt;
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1 @@
+../_assets
diff --git a/docs/kroxylicious-proxy/assemblies b/docs/kroxylicious-proxy/assemblies
@@ -0,0 +1 @@
+../assemblies
diff --git a/docs/kroxylicious-proxy/kroxylicious-proxy.adoc b/docs/kroxylicious-proxy/kroxylicious-proxy.adoc
diff --git a/docs/kroxylicious-proxy/modules b/docs/kroxylicious-proxy/modules
@@ -0,0 +1 @@
+../modules
diff --git 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
@@ -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
@@ -816,15 +816,18 @@
                 </dependencies>
                 <executions>
                     <execution>
-                        <id>convert-to-html</id>
+                        <id>convert-kroxylicious-proxy-to-html</id>
                         <goals>
                             <goal>process-asciidoc</goal>
                         </goals>
                         <configuration>
                             <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>
