From 90c2fd7af5cc23a1710fc9c4057424a1b66b3404 Mon Sep 17 00:00:00 2001
From: Jordi Kroon <jkroon@onyourmarks.agency>
Date: Thu, 30 Apr 2026 22:33:38 +0200
Subject: [PATCH] docs: restructure README and update config namespace

---
 README.md                               | 111 +++++-------------------
 docbookcs.xml.dist                      |   5 +-
 src/Config/ConfigParser.php             |   2 +-
 src/Report/Reporter/ConsoleReporter.php |   4 +-
 tests/Unit/Sniff/SimparaSniffTest.php   |   2 +-
 5 files changed, 28 insertions(+), 96 deletions(-)

diff --git a/README.md b/README.md
index c1bab03..d5a1531 100644
--- a/README.md
+++ b/README.md
@@ -2,96 +2,39 @@
 
 A static-analysis linter for DocBook XML files. It scans XML documentation sources and reports style and convention violations.
 
-## Requirements
+**Full documentation:** [jordikroon.github.io/docbook-cs](https://jordikroon.github.io/docbook-cs)
+
+---
+
+## Contributing
+
+### Requirements
 
 - PHP 8.5+
 - Extensions: `dom`, `libxml`, `simplexml`
 
-## Installation
+### Setup
 
 ```bash
-composer require jordikroon/docbookcs
+composer install
 ```
 
-## Usage
+### Running checks
 
 ```bash
-# Run with the default config file (docbookcs.xml in the current directory)
-vendor/bin/docbook-cs
-
-# Specify a config file
-vendor/bin/docbook-cs --config=myconfig.xml
-
-# Scan specific paths (overrides paths in config)
-vendor/bin/docbook-cs reference/ language/
-
-# Output as Checkstyle XML (useful for CI)
-vendor/bin/docbook-cs --report=checkstyle --no-colors > report.xml
-
-# Output as JSON
-vendor/bin/docbook-cs --report=json
-
-# Suppress progress output
-vendor/bin/docbook-cs --quiet
-```
-
-### Exit codes
-
-| Code | Meaning |
-|------|---------|
-| `0`  | No violations found |
-| `1`  | One or more violations found |
-| `2`  | Runtime error (bad config, unreadable file, etc.) |
-
-## Configuration
+# Tests
+vendor/bin/phpunit
 
-Copy `docbookcs.xml.dist` to `docbookcs.xml` and adjust to your project:
+# Static analysis
+vendor/bin/phpstan
 
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<docbookcs>
-    <sniffs>
-        <sniff class="DocbookCS\Sniff\SimparaSniff" />
-        <sniff class="DocbookCS\Sniff\ExceptionNameSniff" />
-        <sniff class="DocbookCS\Sniff\AttributeOrderSniff" />
-    </sniffs>
-
-    <paths>
-        <path>reference</path>
-        <path>language</path>
-    </paths>
-
-    <exclude>
-        <pattern>*/skeleton.xml</pattern>
-        <pattern>*/.git/*</pattern>
-    </exclude>
-
-    <entities>
-        <directory>../doc-base/entities</directory>
-        <file>entities/global.ent</file>
-    </entities>
-</docbookcs>
+# Code style
+vendor/bin/phpcs
 ```
 
-### `<sniffs>`
-
-Register sniffs by fully-qualified class name. Sniffs support optional `<property>` children for per-sniff configuration (see sniff documentation below).
-
-### `<paths>`
+### Writing a sniff
 
-Directories or files to scan, relative to the config file or absolute. These are used when no paths are passed on the command line.
-
-### `<exclude>`
-
-`fnmatch`-style patterns for paths to skip.
-
-### `<entities>`
-
-Entity directories and files that should be loaded before parsing. Lets the XML parser resolve DocBook entities defined outside the scanned tree (e.g. from `doc-base`).
-
-## Writing a custom sniff
-
-Implement `DocbookCS\Sniff\SniffInterface` (or extend `AbstractSniff`) and register it in your config:
+Implement `DocbookCS\Sniff\SniffInterface` (or extend `AbstractSniff`):
 
 ```php
 namespace Acme\DocbookSniffs;
@@ -114,26 +57,12 @@ final class MySniff extends AbstractSniff
 }
 ```
 
+Register it in your config:
+
 ```xml
 <sniff class="Acme\DocbookSniffs\MySniff" />
 ```
 
-## Development
-
-```bash
-# Install dependencies
-composer install
-
-# Run tests
-vendor/bin/phpunit
-
-# Static analysis
-vendor/bin/phpstan
-
-# Code style
-vendor/bin/phpcs
-```
-
 ## License
 
 Apache 2.0
diff --git a/docbookcs.xml.dist b/docbookcs.xml.dist
index dbc93c0..73ab8c7 100644
--- a/docbookcs.xml.dist
+++ b/docbookcs.xml.dist
@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<docbookcs>
+<docbookcs xmlns="https://jordikroon.github.io/docbook-cs/config"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:schemaLocation="https://jordikroon.github.io/docbook-cs/config
+                               https://jordikroon.github.io/docbook-cs/config.xsd">
     <sniffs>
         <sniff class="DocbookCS\Sniff\SimparaSniff">
             <!-- Optionally add extra block elements that your project uses -->
diff --git a/src/Config/ConfigParser.php b/src/Config/ConfigParser.php
index c1fdf82..36ebf64 100644
--- a/src/Config/ConfigParser.php
+++ b/src/Config/ConfigParser.php
@@ -6,7 +6,7 @@
 
 final class ConfigParser
 {
-    private const string NAMESPACE_URI = 'https://docbookcs.org/config';
+    private const string NAMESPACE_URI = 'https://jordikroon.github.io/docbook-cs/config';
 
     /**
      * @throws ConfigParserException if the file cannot be read or contains invalid XML.
diff --git a/src/Report/Reporter/ConsoleReporter.php b/src/Report/Reporter/ConsoleReporter.php
index 6a81eb1..2599bce 100644
--- a/src/Report/Reporter/ConsoleReporter.php
+++ b/src/Report/Reporter/ConsoleReporter.php
@@ -121,11 +121,11 @@ private function buildPerformance(Report $report): string
 
     private function formatSeverity(Severity $severity): string
     {
-        return match ($severity) {
+        return match ($severity) { // @codeCoverageIgnore
             Severity::ERROR => $this->red(str_pad(Severity::ERROR->name, 7)),
             Severity::WARNING => $this->yellow(str_pad(Severity::WARNING->name, 7)),
             default => $this->dim(str_pad(strtoupper($severity->name), 7)),
-        };
+        }; // @codeCoverageIgnore
     }
 
     private function bold(string $text): string
diff --git a/tests/Unit/Sniff/SimparaSniffTest.php b/tests/Unit/Sniff/SimparaSniffTest.php
index e819550..bb8cdde 100644
--- a/tests/Unit/Sniff/SimparaSniffTest.php
+++ b/tests/Unit/Sniff/SimparaSniffTest.php
@@ -157,7 +157,7 @@ public function itStillFlagsParasOutsideFormalparaWhenSiblingIsFormalpara(): voi
     public function itDoesNotFlagParaInFormalparaRegardlessOfCase(): void
     {
         $doc = $this->createDocument(
-            '<root xmlns="http://docbook.org/ns/docbook">
+            '<root>
                 <formalpara>
                     <title>Title</title>
                     <para>Text</para>