Fix #133: Add docs (#315)

docs/antora.yml

@@ -0,0 +1,5 @@
+name: quarkus-logging-manager
+title: Logging Manager
+version: dev
+nav:
+  - modules/ROOT/nav.adoc

docs/modules/ROOT/nav.adoc

@@ -0,0 +1 @@
+* xref:index.adoc[Logging Manager]

docs/modules/ROOT/pages/includes/attributes.adoc

@@ -0,0 +1,3 @@
+:project-version: 3.0.3
+
+:examples-dir: ./../examples/

docs/modules/ROOT/pages/includes/quarkus-logging-manager.adoc

@@ -0,0 +1,97 @@
+
+:summaryTableId: quarkus-logging-manager
+[.configuration-legend]
+icon:lock[title=Fixed at build time] Configuration property fixed at build time - All other configuration properties are overridable at runtime
+[.configuration-reference.searchable, cols="80,.^10,.^10"]
+|===
+
+h|[[quarkus-logging-manager_configuration]]link:#quarkus-logging-manager_configuration[Configuration property]
+
+h|Type
+h|Default
+
+a|icon:lock[title=Fixed at build time] [[quarkus-logging-manager_quarkus-logging-manager-base-path]]`link:#quarkus-logging-manager_quarkus-logging-manager-base-path[quarkus.logging-manager.base-path]`
+
+
+[.description]
+--
+The base path
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_LOGGING_MANAGER_BASE_PATH+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_LOGGING_MANAGER_BASE_PATH+++`
+endif::add-copy-button-to-env-var[]
+--|string 
+|`logging-manager`
+
+
+a|icon:lock[title=Fixed at build time] [[quarkus-logging-manager_quarkus-logging-manager-openapi-included]]`link:#quarkus-logging-manager_quarkus-logging-manager-openapi-included[quarkus.logging-manager.openapi.included]`
+
+
+[.description]
+--
+Whether or not to include the Logger Manager endpoints in the generated OpenAPI document
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_LOGGING_MANAGER_OPENAPI_INCLUDED+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_LOGGING_MANAGER_OPENAPI_INCLUDED+++`
+endif::add-copy-button-to-env-var[]
+--|boolean 
+|`false`
+
+
+a|icon:lock[title=Fixed at build time] [[quarkus-logging-manager_quarkus-logging-manager-openapi-tag]]`link:#quarkus-logging-manager_quarkus-logging-manager-openapi-tag[quarkus.logging-manager.openapi-tag]`
+
+
+[.description]
+--
+The tag to use if OpenAPI is included
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_LOGGING_MANAGER_OPENAPI_TAG+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_LOGGING_MANAGER_OPENAPI_TAG+++`
+endif::add-copy-button-to-env-var[]
+--|string 
+|`Logging-manager`
+
+
+a|icon:lock[title=Fixed at build time] [[quarkus-logging-manager_quarkus-logging-manager-always-include]]`link:#quarkus-logging-manager_quarkus-logging-manager-always-include[quarkus.logging-manager.always-include]`
+
+
+[.description]
+--
+Always include this. By default this will always be included. Setting this to false will also exclude this in Prod
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_LOGGING_MANAGER_ALWAYS_INCLUDE+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_LOGGING_MANAGER_ALWAYS_INCLUDE+++`
+endif::add-copy-button-to-env-var[]
+--|boolean 
+|`true`
+
+
+a| [[quarkus-logging-manager_quarkus-logging-manager-enable]]`link:#quarkus-logging-manager_quarkus-logging-manager-enable[quarkus.logging-manager.enable]`
+
+
+[.description]
+--
+If Logging Manager should be enabled. By default, Logging Manager is enabled if it is included (see `always-include`).
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_LOGGING_MANAGER_ENABLE+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_LOGGING_MANAGER_ENABLE+++`
+endif::add-copy-button-to-env-var[]
+--|boolean 
+|`true`
+
+|===

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,60 @@
+= Quarkus Logging Manager
+
+include::./includes/attributes.adoc[]
+
+The Quarkus Logging Manager Extension provides you endpoints to visualize and manage the log level of your loggers.
+
+== Installation
+
+If you want to use this extension, you need to add the `io.quarkiverse.loggingmanager:quarkus-logging-manager` extension first to your build file.
+
+For instance, with Maven, add the following dependency to your POM file:
+
+[source,xml,subs=attributes+]
+----
+<dependency>
+    <groupId>io.quarkiverse.loggingmanager</groupId>
+    <artifactId>quarkus-logging-manager</artifactId>
+    <version>${logger-manager.version}</version>
+    <scope>runtime</scope>
+</dependency>
+
+----
+
+== OpenAPI
+
+You can include the Logger Manager API in the OpenAPI document (and thus also Swagger UI). This needs to be enabled via config:
+
+[source,properties]
+----
+quarkus.logging-manager.openapi.included=true
+----
+
+Simply run your application with `mvn quarkus:dev` and execute your code. This will then add the following to your OpenAPI:
+
+image::openapi.png[Logging Manager OpenAPI]
+
+== Security
+
+Security of endpoints is important and we do not want to allow unknown people to know (or worse, change!) the log levels of our applications. 
+Fortunately we can secure our endpoints using Quarkus' default security mechanism, as described in Security Overview. 
+All you have to do is define your application.properties similar to this:
+
+[source,properties]
+----
+quarkus.http.auth.basic=true # If you want basic auth. Multiple auth mechanism are supported
+
+quarkus.http.auth.policy.admin-access.roles-allowed=admin
+quarkus.http.auth.permission.roles1.paths=/q/logging-manager
+quarkus.http.auth.permission.roles1.policy=admin-access
+----
+
+And, in case you chose Basic Auth, provide a IdentityProvider (either by implementing one or adding an extension that provides one). 
+Quarkus will take care of matching the paths (in this case /q/logging-manager to the policy you defined and granting or denying access). 
+Then you can also secure all the endpoints in your application using this configuration.
+
+
+[[extension-configuration-reference]]
+== Extension Configuration Reference
+
+include::includes/quarkus-logging-manager.adoc[leveloffset=+1, opts=optional]

docs/pom.xml

@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.quarkiverse.loggingmanager</groupId>
+        <artifactId>quarkus-logging-manager-parent</artifactId>
+        <version>3.0.4-SNAPSHOT</version>
+        <relativePath>../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>quarkus-logging-manager-docs</artifactId>
+    <name>Quarkus - Logging Manager - Documentation</name>
+
+    <dependencies>
+        <!-- Make sure the doc is built after the other artifacts -->
+        <dependency>
+            <groupId>io.quarkiverse.loggingmanager</groupId>
+            <artifactId>quarkus-logging-manager-deployment</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <sourceDirectory>modules/ROOT/examples</sourceDirectory>
+        <plugins>
+            <plugin>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>build</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>it.ozimov</groupId>
+                <artifactId>yaml-properties-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <phase>initialize</phase>
+                        <goals>
+                            <goal>read-project-properties</goal>
+                        </goals>
+                        <configuration>
+                            <files>
+                                <file>${project.basedir}/../.github/project.yml</file>
+                            </files>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <artifactId>maven-resources-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-resources</id>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${project.basedir}/modules/ROOT/pages/includes/</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>${project.basedir}/../target/asciidoc/generated/config/</directory>
+                                    <include>quarkus-logging-manager.adoc</include>
+                                    <filtering>false</filtering>
+                                </resource>
+                                <resource>
+                                    <directory>${project.basedir}/templates/includes</directory>
+                                    <include>attributes.adoc</include>
+                                    <filtering>true</filtering>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>copy-images</id>
+                        <phase>prepare-package</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${project.build.directory}/generated-docs/_images/</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>${project.basedir}/modules/ROOT/assets/images/</directory>
+                                    <filtering>false</filtering>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.asciidoctor</groupId>
+                <artifactId>asciidoctor-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

docs/templates/includes/attributes.adoc

@@ -0,0 +1,3 @@
+:project-version: ${release.current-version}
+
+:examples-dir: ./../examples/

pom.xml

@@ -18,6 +18,7 @@
     <modules>
         <module>deployment</module>
         <module>runtime</module>
+        <module>docs</module>
     </modules>
 
     <scm>

runtime/src/main/resources/META-INF/quarkus-extension.yaml

@@ -14,3 +14,4 @@ metadata:
   config:
     - "quarkus.logging-manager."
   status: "stable"
+  guide: "https://quarkiverse.github.io/quarkiverse-docs/quarkus-logging-manager/dev/index.html"