Finalize the port of the documentation to MkDocs

.github/workflows/ci.yaml

@@ -0,0 +1,53 @@
+name: continuous-integration
+on: push
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch sources
+        uses: actions/checkout@v4
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          coverage: none
+          extensions: curl, intl, mbstring, simplexml
+          php-version: 8.3
+      - name: Get cache directory
+        id: cache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{steps.cache.outputs.dir}}
+          key: ${{runner.os}}-composer-${{hashFiles('**/composer.lock')}}
+          restore-keys: ${{runner.os}}-composer-
+      - name: Install dependencies
+        run: composer install
+      - name: Run tests
+        run: composer test
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch sources
+        uses: actions/checkout@v4
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          coverage: none
+          extensions: curl, intl, mbstring, simplexml
+          php-version: 8.3
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          cache: pip
+          python-version: 3.12
+      - name: Install dependencies
+        run: |
+          curl --location --output var/castor.phar https://github.com/jolicode/castor/releases/latest/download/castor.linux-amd64.phar
+          pip install --requirement=etc/requirements.txt
+      - name: Deploy documentation
+        run: |
+          php var/castor.phar doc
+          mkdocs gh-deploy --config-file=etc/mkdocs.yaml --force

castor.php

@@ -1,7 +1,7 @@
 <?php
 use Castor\Attribute\{AsContext, AsTask};
 use Castor\Context;
-use function Castor\{exit_code, finder, fs, run, variable};
+use function Castor\{exit_code, finder, fs, request, run, variable};
 
 #[AsContext(default: true)]
 function context(): Context {
@@ -16,15 +16,17 @@ function clean(): void {
 
 #[AsTask(description: "Builds the documentation")]
 function doc(): void {
+	foreach (["CHANGELOG.md", "LICENSE.md"] as $file) fs()->copy($file, "docs/".mb_strtolower($file));
+
 	$pkg = variable("package");
 	file_put_contents(
 		$file = "etc/phpdoc.xml",
 		preg_replace('/version number="\d+(\.\d+){2}"/', "version number=\"$pkg->version\"", file_get_contents($file))
 	);
 
-	foreach (["CHANGELOG.md", "LICENSE.md"] as $file) fs()->copy($file, "docs/".mb_strtolower($file));
 	fs()->remove("docs/api");
-	run("phpdoc --config=etc/phpdoc.xml");
+	file_put_contents("var/phpDocumentor.phar", request("GET", "https://phpdoc.org/phpDocumentor.phar")->getContent());
+	run("php var/phpDocumentor.phar --config=etc/phpdoc.xml");
 	fs()->copy("docs/favicon.ico", "docs/api/images/favicon.ico");
 }
 
@@ -39,6 +41,12 @@ function publish(): void {
 	foreach (["tag", "push origin"] as $action) run("git $action v$pkg->version");
 }
 
+#[AsTask(description: "Starts the development server")]
+function serve(): void {
+	doc();
+	run("mkdocs serve --config-file=etc/mkdocs.yaml");
+}
+
 #[AsTask(description: "Runs the test suite")]
 function test(): int {
 	return exit_code("php vendor/bin/phpunit --configuration=etc/phpunit.xml");

docs/index.md

@@ -16,7 +16,3 @@ The `Report` class, the main one, provides the parsing and formatting features.
 
 - [Parse coverage data from a LCOV file](usage/parsing.md)
 - [Format coverage data to the LCOV format](usage/formatting.md)
-
-## See also
-- [API reference](api/)
-- [Packagist package](https://packagist.org/packages/cedx/lcov)

docs/installation.md

@@ -27,7 +27,7 @@ composer require cedx/lcov
 Now in your [PHP](https://www.php.net) code, you can use:
 
 ```php
-use lcov\{
+<?php use lcov\{
   BranchCoverage, BranchData,
   FunctionCoverage, FunctionData,
   LineCoverage, LineData,

docs/usage/formatting.md

@@ -4,7 +4,7 @@ formatted as [LCOV](https://github.com/linux-test-project/lcov) string.
 All you have to do is to create the adequate structure using these different classes, and to export the final result:
 
 ```php
-use lcov\{FunctionCoverage, LineCoverage, LineData, Report, SourceFile};
+<?php use lcov\{FunctionCoverage, LineCoverage, LineData, Report, SourceFile};
 
 $sourceFile = new SourceFile(
   path: "/home/cedx/lcov.php/fixture.php",
@@ -33,4 +33,5 @@ LH:2
 end_of_record
 ```
 
-> See the [API reference](api/) of this library for detailed information on the available classes.
+!!! tip
+    See the [API reference](../api/) of this library for detailed information on the available classes.

docs/usage/parsing.md

@@ -3,7 +3,7 @@ The `Report::parse()` static method parses a [LCOV](https://github.com/linux-tes
 and creates a `Report` instance giving detailed information about this coverage report:
 
 ```php
-use lcov\Report;
+<?php use lcov\Report;
 
 try {
   $report = Report::parse((string) file_get_contents("/path/to/lcov.info"));
@@ -16,7 +16,8 @@ catch (InvalidArgumentException $e) {
 }
 ```
 
-> An `InvalidArgumentException` is thrown if any error occurred while parsing the coverage report.
+!!! note
+    An `InvalidArgumentException` is thrown if any error occurred while parsing the coverage report.
 
 Converting the `Report` instance to [JSON](https://www.json.org) format will return a map like this:
 
@@ -51,4 +52,5 @@ Converting the `Report` instance to [JSON](https://www.json.org) format will ret
 }
 ```
 
-> See the [API reference](api/) of this library for more information on the `Report` class.
+!!! tip
+    See the [API reference](../api/) of this library for more information on the `Report` class.

etc/mkdocs.yaml

@@ -0,0 +1,62 @@
+site_name: LCOV Reports for PHP
+site_url: https://docs.belin.io/lcov.php
+site_author: Cédric Belin - [email protected]
+site_description: >
+  Parse and format to LCOV your code coverage reports, in PHP.
+  The best way to share your code coverage stats.
+
+docs_dir: ../docs
+site_dir: ../www
+use_directory_urls: false
+
+edit_uri: edit/main/docs/
+repo_name: cedx/lcov.php
+repo_url: https://github.com/cedx/lcov.php
+
+copyright: Copyright © Cédric Belin
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/cedx
+      name: GitHub
+    - icon: fontawesome/brands/linkedin
+      link: https://linkedin.com/in/cedxbelin
+      name: LinkedIn
+    - icon: fontawesome/brands/mastodon
+      link: https://mastodon.social/@cedx
+      name: Mastodon
+
+extra_css:
+  - styles.css
+
+markdown_extensions:
+  - admonition
+  - pymdownx.superfences
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Usage:
+      - LCOV parsing: usage/parsing.md
+      - LCOV formatting: usage/formatting.md
+  - See also:
+      - API reference: api/
+      - Changelog: changelog.md
+      - License: license.md
+
+theme:
+  favicon: favicon.svg
+  features:
+    - content.code.copy
+    - content.tooltips
+    - navigation.footer
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.sections
+    - search.suggest
+  font: false
+  logo: favicon.svg
+  name: material
+  palette:
+    accent: indigo
+    primary: indigo