Move development information into documentation and improve general R…

…EADME

Signed-off-by: Tim Walter <[email protected]>

README.md

@@ -1,45 +1,40 @@
 # kcwarden - Keycloak Configuration Auditor
 
-[kcwarden](https://iteratec.github.io/kcwarden/) checks your Keycloak configuration for common misconfigurations and security vulnerabilities.
+![Python](https://img.shields.io/pypi/pyversions/kcwarden.svg)
+[![PyPI version](https://img.shields.io/pypi/v/kcwarden.svg)](https://pypi.python.org/pypi/kcwarden)
+[![Mkdocs](https://img.shields.io/badge/doc-mkdocs-845ed7.svg)](https://iteratec.github.io/kcwarden)
+[![GitHub discussions](https://img.shields.io/badge/discuss-online-845ef7)](https://github.com/iteratec/kcwarden/discussions)
+[![Downloads](https://pepy.tech/badge/kcwarden)](https://pepy.tech/project/kcwarden)
+[![GitHub stars](https://img.shields.io/github/stars/iteratec/kcwarden?style=flat)](https://github.com/iteratec/kcwarden/stargazers)
 
-## Installation and Usage
+[![last release status](https://github.com/iteratec/kcwarden/actions/workflows/publish.yaml/badge.svg)](https://github.com/iteratec/kcwarden/actions/workflows/publish.yaml)
 
-Please see our [documentation on the project website](https://iteratec.github.io/kcwarden/).
+**[kcwarden](https://iteratec.github.io/kcwarden/) checks your Keycloak configuration for common misconfigurations and
+security vulnerabilities.**
 
-## Development
+## 🚀 Getting started
 
-### Docker Image
+Install it using Python:
 
-To build a Docker image with a bundled kcwarden, you can use:
+````shell
+pip install kcwarden
+````
 
-```shell
-docker build -f Docker/Dockerfile -t kcwarden:0.0.1 .
-```
+For details and other methods, see our [documentation](https://iteratec.github.io/kcwarden/installation/).
 
-or
+## ▶️ Usage
 
-```shell
-buildah build -f Docker/Dockerfile -t kcwarden:0.0.1 .
-```
+Download your Keycloak's config:
 
-It uses a multi-stage build to first build the application as Python wheel and afterwards install this wheel in a second
-image.
+````shell
+kcwarden download --realm $REALM --user admin --output config.json $KEYCLOAK_BASE_URL
+````
 
-### Tests
+and run the checks against it:
 
-The unit tests can be run with `poetry run pytest`.
+````shell
+kcwarden audit config.json
+````
 
-The integration tests that actually start Keycloak containers using Docker can be executed
-with `poetry run pytest --integration`.
-The Keycloak versions for which the tests are executed can be found in [`conftest.py`](./tests/integration/conftest.py).
-It can be overridden by setting the environment variable `INTEGRATION_TEST_KEYCLOAK_VERSIONS` to a space-separated list
-of Keycloak container image tags (see [quay.io](https://quay.io/repository/keycloak/keycloak?tab=tags)).
+For more information, see the [documentation on the project website](https://iteratec.github.io/kcwarden/).
 
-### Build the Docs
-
-The documentation is created using [MkDocs](https://www.mkdocs.org/) and lives in the [`docs`](./docs) directory.
-The dependencies for _MkDocs_ can be installed using this command: `poetry install --with docs`.
-Afterward, the documentation can be built using `poetry run mkdocs build`.
-The static output is then located in the `site` directory.
-A development server that serves the documentation, watches for changes and automatically re-creates the site can be
-spun up using `poetry run mkdocs serve`.

docs/development.md

@@ -0,0 +1,62 @@
+# Development
+
+kcwarden uses [Poetry](https://python-poetry.org/) for dependency management and bundling.
+You might want to use [pipx](https://github.com/pypa/pipx) to install Poetry.
+
+After Poetry is set up, you can install all dependencies (including development dependencies) using `poetry install`.
+
+If the package is build, the version is determined by the git tag.
+Thus, a Poetry plugin is used that must be installed using `poetry self add "poetry-dynamic-versioning[plugin]`.
+It also requires that you have git installed on your system.
+
+# Linting and Formatting
+
+`ruff` is used as linter and code formatter.
+It can be executed using `poetry run ruff . --fix` for linting with automatic fixes and `poetry run ruff format .` for
+formatting.
+
+The pipeline only succeeds if the code is formatted and there are no linting issues.
+
+# Tests
+
+The unit tests can be run with `poetry run pytest`.
+
+The integration tests that actually start Keycloak containers using Docker can be executed
+with `poetry run pytest --integration`.
+The Keycloak versions for which the tests are executed can be found in [`conftest.py`](./tests/integration/conftest.py).
+It can be overridden by setting the environment variable `INTEGRATION_TEST_KEYCLOAK_VERSIONS` to a space-separated list
+of Keycloak container image tags (see [quay.io](https://quay.io/repository/keycloak/keycloak?tab=tags)).
+
+# Docker Image
+
+To build a Docker image with a bundled kcwarden from the local repository, you can use:
+
+```shell
+docker build -f Docker/Dockerfile -t kcwarden:latest .
+```
+
+or
+
+```shell
+buildah build -f Docker/Dockerfile -t kcwarden:latest .
+```
+
+It uses a multi-stage build to first build the application as Python wheel and afterward install this wheel in a second
+image.
+
+# Release
+
+kcwarden is released as Python package on [PyPI](https://pypi.org/project/kcwarden/) and as Docker image
+on [ghcr.io](https://github.com/iteratec/kcwarden/pkgs/container/kcwarden).
+
+For publishing these artifacts, a release is created on GitHub and then a GitHub workflow creates and publishes the
+packages.
+
+# Build the Docs
+
+The documentation is created using [MkDocs](https://www.mkdocs.org/) and lives in the `docs` directory.
+The dependencies for _MkDocs_ can be installed using this command: `poetry install --with docs`.
+Afterward, the documentation can be built using `poetry run mkdocs build`.
+The static output is then located in the `site` directory.
+A development server that serves the documentation, watches for changes and automatically re-creates the site can be
+spun up using `poetry run mkdocs serve`.

mkdocs.yml

@@ -21,6 +21,7 @@ nav:
   - index.md
   - installation.md
   - usage.md
+  - development.md
   - Auditors:
       - auditors/index.md
       - auditors/clients.md