documentation with mkdocs-material (#141)

* introduce mkdocs

* update API docs after rebase

* UI: change app settings' icon

* UI: bump htmx to 2.0.5

* expose swagger-ui only in DEV env

* UI: update docs links

* docs: draft docs structure & add configuration sections

* update /health endpoint specs

* remove unnecessary, explicit i18n config

* add ko-fi banner

* enable footer navigation

* remove analytics and cookie consent

* add sponsorship to the UI

* docs: update & improve API docs

* docs: update public PagerDuty setup guide

* update feature request template

* actualise README.md

* finalize docs

* add GH workflow to deploy docs

* docs: fix social images URLs in prod

Author: adamkobor

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,14 +7,14 @@ assignees: ''
 
 ---
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+**What is your feature request related to?**
+A clear and concise description of the feature you want to request. For example, "I would like to see a new notification channel for SMS alerts."
 
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.
 
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
 **Additional context**
 Add any other context or screenshots about the feature request here.
+
+**Would you like to contribute to this feature?**
+Please let us know if you are interested in contributing to this feature. We would be happy to assist you with the development process.

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: docs-deploy
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install -r requirements.txt
+      - run: mkdocs gh-deploy --force

README.md

@@ -1,4 +1,4 @@
-![Kuvasz](https://github.com/kuvasz-uptime/kuvasz/raw/main/docs/kuvasz_banner.png)
+![Kuvasz](docs/docs/images/kuvasz_banner.webp)
 
 [![CI](https://github.com/kuvasz-uptime/kuvasz/actions/workflows/main.yml/badge.svg)](https://github.com/kuvasz-uptime/kuvasz/actions/workflows/main.yml)
 [![codecov](https://codecov.io/gh/kuvasz-uptime/kuvasz/branch/main/graph/badge.svg?token=67X0CD3CGY)](https://codecov.io/gh/kuvasz-uptime/kuvasz)
@@ -8,82 +8,37 @@
 
 ---
 
-## ℹ️ What is Kuvasz?
+## [Documentation](https://kuvasz-uptime.dev)
 
-Kuvasz is a **headless uptime monitor service**, which means that it is able to watch all of your precious websites and notifies you if something bad happens to them.
+## ℹ️  What is Kuvasz?
 
-### Where does the name come from?
+**Kuvasz** [ˈkuvɒs], an open-source, self-hosted uptime & SSL monitoring service, designed to help you keep track of your websites and services. It provides a modern, user-friendly interface, a powerful REST API, and supports multiple notification channels like email, Slack, Telegram, and PagerDuty.
 
-Kuvasz (pronounce as [ˈkuvɒs]) is an ancient hungarian breed of livestock & guard dog. You can read more about them on [Wikipedia](https://en.wikipedia.org/wiki/Kuvasz).
+![Kuvasz](docs/docs/images/feature_carousel.webp)
 
-### Features
+### Where does the name come from?
 
-- Uptime & latency monitoring with a configurable interval
-- SSL certification monitoring (once a day)
-- Email notifications through SMTP
-- Slack notifications through webhoooks
-- Telegram notifications through the Bot API
-- [PagerDuty integration](https://github.com/kuvasz-uptime/kuvasz/blob/main/docs/Integrating-with-PagerDuty.md) with automatic incident resolution
-- Configurable data retention period
+Kuvasz (pronounce as [ˈkuvɒs]) is an ancient hungarian breed of livestock & guard dog. You can read more about them on [Wikipedia](https://en.wikipedia.org/wiki/Kuvasz).
 
-### Future ideas 🚧
+## ✨ Features
 
-- Regular Lighthouse audits for your websites
+- **HTTP(S) monitoring**: Monitor the availability and performance of your websites and services by sending HTTP(S) requests.
+- **SSL certification monitoring**: Automatically check the SSL certificates of your monitored services to ensure they are valid and not expired.
+- **Notifications on a per-monitor basis**: Configure different notification channels for each monitor, allowing you to tailor alerts to your specific needs.
+- **Sleek UI**: Kuvasz has a modern, responsive, and user-friendly interface that makes it easy to manage your monitors.
+- **Full-fledged REST API**: Manage your monitors, check their status, and more through a powerful API.
+- More to come: _Kuvasz_ is under active development, and more features are planned for the future, such as **response keyword matching**, **POST requests with arbitrary payload**, and more.
 
 ## ⚡️  Quick start guide
 
-### Requirements
-
-- You have **a running PostgreSQL instance** (Preferably 12+)
-
-### Starting Kuvasz
-
-The quickest way to spin up an instance of Kuvasz is something like this:
-
-```shell
-docker run -p 8080:8080 \
--e ADMIN_USER=admin \
--e ADMIN_PASSWORD=ThisShouldBeVeryVerySecure \
--e DATABASE_HOST=127.0.0.1 \
--e DATABASE_PORT=5432 \
--e DATABASE_NAME=your_database \
--e DATABASE_USER=your_db_user \
--e DATABASE_PASSWORD=OhThisIsSoSecure \
--e JWT_SIGNATURE_SECRET=testSecretItsVeryVerySecretSecret \
-kuvaszmonitoring/kuvasz:latest
-```
+If you want to get started quickly, please refer to the [**Installation guide**](https://kuvasz-uptime.dev/setup/installation/) in the documentation.
 
-At this point you shouldn't see any error in your logs, so you're able to create your first monitor with an API call. Please, take a look at the [**API section**](https://github.com/kuvasz-uptime/kuvasz/wiki/API) of the Wiki, to get familiar with the authentication method that Kuvasz provides.
-If you have a valid access token, then creating a monitor and scheduling an uptime check for it, is simple like that:
+## ☕️ Do you like it?
 
-```shell
-curl --location --request POST 'https://your.host:8080/api/v1/monitors/' \
---header 'Authorization: Bearer YourAccessToken' \
---header 'Content-Type: application/json' \
---data-raw '{
-    "name": "my_first_monitor",
-    "url": "https://website.to.check",
-    "uptimeCheckInterval": 60
-}'
-```
+While _Kuvasz_ is free and open-source, it still requires a lot of time and effort to maintain and develop. If you like it, please consider supporting the project by **starring it on GitHub**, or by **donating** via Ko-fi:
 
-You can read more about the **monitor management** in the [dedicated section](https://github.com/kuvasz-uptime/kuvasz/wiki/Monitor-management) of the Wiki.
-
-## ⛴ Deployment
-
-Although the example above is simple, when you want to deploy Kuvasz to production you'll probably end up with a more mature tooling or configuration. You can find the available **configuration properties [here](https://github.com/kuvasz-uptime/kuvasz/wiki/Configuration)**.
-If you are going to deploy Kuvasz with **docker-compose or Kubernetes**, you should take a look at the [**deployment related examples**](https://github.com/kuvasz-uptime/kuvasz/tree/main/examples), or the [**Deployment**](https://github.com/kuvasz-uptime/kuvasz/wiki/Deployment) section of the Wiki.
-
-## 📚 Further reading
-
-If you want to know more about the fundamentals of Kuvasz, head to the [**Events & Event handlers**](https://github.com/kuvasz-uptime/kuvasz/wiki/Events-&-Event-handlers) section!
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L4L31DH59D)
 
 ## ⁉️ Do you have a question?
 
 Let's go to the [discussions](https://github.com/kuvasz-uptime/kuvasz/discussions)!
-
-## ❤️ Sponsors
-
-[![JetBrains](https://github.com/kuvasz-uptime/kuvasz/raw/main/docs/jetbrains-logo.png)](https://www.jetbrains.com/?from=kuvasz)
-
-Thanks to [JetBrains](https://www.jetbrains.com/?from=kuvasz) for supporting the development of Kuvasz with their Open Source License Program 🙏

app/build.gradle.kts

@@ -168,7 +168,7 @@ jib {
 val updateApiDoc by tasks.registering(type = Copy::class) {
     dependsOn("kaptKotlin")
     from(layout.buildDirectory.file("tmp/kapt3/classes/main/META-INF/swagger/kuvasz-latest.yml"))
-    into("$rootDir/docs/api-doc")
+    into("$rootDir/docs/docs/api-doc")
 }
 
 val localDbUrl: String by project

app/src/main/kotlin/com/kuvaszuptime/kuvasz/controllers/MonitorOperations.kt

@@ -27,7 +27,7 @@ import java.time.Duration
 
 interface MonitorOperations {
 
-    @Operation(summary = "Returns all monitors with their details")
+    @Operation(summary = "Get all monitors with their details")
     @Get("/")
     fun getMonitorsWithDetails(
         @QueryValue
@@ -44,34 +44,36 @@ interface MonitorOperations {
         sslCheckEnabled: Boolean?,
     ): List<MonitorDetailsDto>
 
-    @Operation(summary = "Returns a monitor's details")
+    @Operation(summary = "Get a monitor's details")
     @Get("/{monitorId}")
     fun getMonitorDetails(monitorId: Long): MonitorDetailsDto
 
-    @Operation(summary = "Creates a monitor")
+    @Operation(summary = "Create a monitor")
     @Post("/")
     fun createMonitor(@Body monitor: MonitorCreateDto): MonitorDto
 
-    @Operation(summary = "Deletes a monitor by ID")
+    @Operation(summary = "Delete a monitor by ID")
     @Delete("/{monitorId}")
     fun deleteMonitor(monitorId: Long)
 
     @Operation(
-        summary = "Updates a monitor by ID",
+        summary = "Update a monitor by ID",
+        description = "Updates the monitor with the given ID. Only fields that are present in the request body " +
+            "will be updated. Fields not present in the request body will remain unchanged.",
         requestBody = RequestBody(content = [Content(schema = Schema(implementation = MonitorUpdateDto::class))])
     )
     @Patch("/{monitorId}")
     fun updateMonitor(monitorId: Long, @Body updates: ObjectNode): MonitorDto
 
-    @Operation(summary = "Returns the uptime events of the given monitor")
+    @Operation(summary = "Get the uptime events of the given monitor")
     @Get("/{monitorId}/uptime-events")
     fun getUptimeEvents(monitorId: Long): List<UptimeEventDto>
 
-    @Operation(summary = "Returns the SSL events of the given monitor")
+    @Operation(summary = "Get the SSL events of the given monitor")
     @Get("/{monitorId}/ssl-events")
     fun getSSLEvents(monitorId: Long): List<SSLEventDto>
 
-    @Operation(summary = "Returns the stats of the given monitor")
+    @Operation(summary = "Get the stats of the given monitor")
     @Get("/{monitorId}/stats")
     fun getMonitorStats(
         monitorId: Long,
@@ -83,11 +85,11 @@ interface MonitorOperations {
         period: Duration?,
     ): MonitorStatsDto
 
-    @Operation(summary = "Returns the export of all monitors in YAML format")
+    @Operation(summary = "Download the export of all monitors in YAML format")
     @Get("/export/yaml")
     fun getYamlMonitorsExport(): SystemFile
 
-    @Operation(summary = "Returns the overall, cumulative stats of all monitors")
+    @Operation(summary = "Get the overall, cumulative stats of all monitors")
     @Get("/stats")
     fun getMonitoringStats(
         @QueryValue

app/src/main/kotlin/com/kuvaszuptime/kuvasz/controllers/SettingsOperations.kt

@@ -6,7 +6,7 @@ import io.swagger.v3.oas.annotations.Operation
 
 interface SettingsOperations {
 
-    @Operation(summary = "Returns the current settings of the application")
+    @Operation(summary = "Get the current settings of the application")
     @Get("/")
     fun getSettings(): SettingsDto
 }

app/src/main/resources/application.yml

@@ -3,7 +3,6 @@ micronaut:
   application:
     name: kuvasz
   openapi:
-    views.spec: 'swagger-ui.enabled=true'
     additional:
       files: 'src/main/resources/swagger'
   security:
@@ -42,10 +41,6 @@ micronaut:
         access: isAnonymous()
       - pattern: /api/v1/info
         access: isAnonymous()
-      - pattern: /swagger-ui/**
-        access: isAnonymous()
-      - pattern: /swagger/**
-        access: isAnonymous()
       - pattern: /api/**
         access:
           - ROLE_API
@@ -56,12 +51,6 @@ micronaut:
         access: isAnonymous()
   router:
     static-resources:
-      swagger:
-        paths: classpath:META-INF/swagger
-        mapping: /swagger/**
-      swagger-ui:
-        paths: classpath:META-INF/swagger/views/swagger-ui
-        mapping: /swagger-ui/**
       public:
         paths: classpath:public
         mapping: /public/**

app/src/main/resources/swagger/additional-endpoints.yml

@@ -8,7 +8,7 @@ paths:
       tags:
         - Management operations
       summary: Health endpoint
-      description: Returns the current status of the application
+      description: General health check endpoint
       operationId: health
       parameters: []
       responses:
@@ -29,8 +29,6 @@ components:
     HealthResult:
       type: object
       properties:
-        name:
-          type: string
         status:
           type: string
           enum:

docs/.gitignore

@@ -0,0 +1,2 @@
+.cache
+site

docs/.python-version

@@ -0,0 +1 @@
+3.13