Merge pull request #196 from patchlevel/renovate-docs

renovate docs

.github/workflows/docs-build-try.yml

@@ -0,0 +1,29 @@
+name: Try build docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - "renovate/*"
+
+jobs:
+  build-try:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build docs
+        working-directory: docs/
+        run: |
+          mkdocs build --strict

.github/workflows/docs-check.yml

@@ -0,0 +1,49 @@
+# https://help.github.com/en/categories/automating-your-workflow-with-github-actions
+
+name: "Check Docs"
+
+on:
+    pull_request:
+    push:
+        branches:
+            - "[0-9]+.[0-9]+.x"
+
+jobs:
+    checkdocs:
+        name: "Check Docs"
+
+        runs-on: ${{ matrix.operating-system }}
+
+        strategy:
+            matrix:
+                dependencies:
+                    - "locked"
+                php-version:
+                    - "8.3"
+                operating-system:
+                    - "ubuntu-latest"
+
+        steps:
+            - name: "Checkout"
+              uses: actions/checkout@v4
+
+            - name: "Install PHP"
+              uses: "shivammathur/setup-php@2.30.3"
+              with:
+                  coverage: none
+                  php-version: "${{ matrix.php-version }}"
+                  ini-values: memory_limit=-1, opcache.enable_cli=1
+                  extensions: pdo_sqlite
+
+            - uses: ramsey/composer-install@3.0.0
+              with:
+                dependency-versions: ${{ matrix.dependencies }}
+
+            - name: "extract php code"
+              run: "bin/docs-extract-php-code"
+
+            - name: "lint php"
+              run: "php -l docs_php/*.php"
+
+            - name: "docs code style"
+              run: "vendor/bin/phpcbf docs_php --exclude=SlevomatCodingStandard.TypeHints.DeclareStrictTypes"

Makefile

@@ -40,3 +40,34 @@ test: phpunit
 
 .PHONY: dev
 dev: static test                                                                ## run dev tools
+
+.PHONY: docs
+docs: mkdocs                                                                          ## run mkdocs
+	cd docs && python3 -m mkdocs serve
+
+.PHONY: mkdocs
+mkdocs:                                                                         ## run mkdocs
+	cd docs && pip3 install -r requirements.txt
+
+.PHONY: docs-extract-php
+docs-extract-php:
+	bin/docs-extract-php-code
+
+.PHONY: docs-inject-php
+docs-inject-php:
+	bin/docs-inject-php-code
+
+.PHONY: docs-format
+docs-format: docs-phpcs docs-inject-php
+
+.PHONY: docs-php-lint
+docs-php-lint: docs-extract-php
+	php -l docs_php/*.php
+
+.PHONY: docs-phpcs
+docs-phpcs: docs-extract-php
+	vendor/bin/phpcbf docs_php --exclude=SlevomatCodingStandard.TypeHints.DeclareStrictTypes || true
+
+.PHONY: docs-psalm
+docs-psalm: docs-extract-php
+	vendor/bin/psalm --config=psalm_docs.xml

bin/docs-extract-php-code

@@ -0,0 +1,53 @@
+#!/usr/bin/env php
+<?php
+
+use League\CommonMark\Environment\Environment;
+use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;
+use League\CommonMark\Node\Query;
+use League\CommonMark\Parser\MarkdownParser;
+use Wnx\CommonmarkMarkdownRenderer\MarkdownRendererExtension;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$environment = new Environment([]);
+$environment->addExtension(new MarkdownRendererExtension());
+
+$parser = new MarkdownParser($environment);
+
+$targetDir = __DIR__ . '/../docs_php';
+
+if (file_exists($targetDir)) {
+    exec('rm -rf ' . $targetDir);
+}
+
+mkdir($targetDir);
+
+$finder = new Symfony\Component\Finder\Finder();
+$finder->files()->in(__DIR__ . '/../docs/pages')->name('*.md');
+
+foreach ($finder as $file) {
+    $fileName = pathinfo($file->getBasename(), PATHINFO_FILENAME);
+
+    $content = file_get_contents($file->getPathname());
+    $document = $parser->parse($content);
+
+    $result = (new Query())
+        ->where(Query::type(FencedCode::class))
+        ->findAll($document);
+
+    /**
+     * @var FencedCode $node
+     */
+    foreach ($result as $i => $node) {
+        if ($node->getInfo() !== 'php') {
+            continue;
+        }
+
+        $source = sprintf('%s:%s', $file->getRealPath(), $node->getStartLine());
+
+        $code = "<?php\n// " . $source . "\n\n" . $node->getLiteral();
+
+        $targetPath = $targetDir . '/' . $fileName . '_' . $i . '.php';
+        file_put_contents($targetPath, $code);
+    }
+}

bin/docs-inject-php-code

@@ -0,0 +1,70 @@
+#!/usr/bin/env php
+<?php
+
+use League\CommonMark\Environment\Environment;
+use League\CommonMark\Extension\CommonMark\Node\Block\FencedCode;
+use League\CommonMark\Node\Query;
+use League\CommonMark\Parser\MarkdownParser;
+use Wnx\CommonmarkMarkdownRenderer\MarkdownRendererExtension;
+use Wnx\CommonmarkMarkdownRenderer\Renderer\MarkdownRenderer;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+
+
+$environment = new Environment([]);
+$environment->addExtension(new MarkdownRendererExtension());
+
+$parser = new MarkdownParser($environment);
+$markdownRenderer = new MarkdownRenderer($environment);
+
+$targetDir = __DIR__ . '/../docs_php';
+
+if (!file_exists($targetDir)) {
+    exit(1);
+}
+
+$finder = new Symfony\Component\Finder\Finder();
+$finder->files()->in(__DIR__ . '/../docs/pages')->name('*.md');
+
+foreach ($finder as $file) {
+    $fileName = pathinfo($file->getBasename(), PATHINFO_FILENAME);
+
+    $content = file_get_contents($file->getPathname());
+    $document = $parser->parse($content);
+
+    $result = (new Query())
+        ->where(Query::type(FencedCode::class))
+        ->findAll($document);
+
+    /**
+     * @var FencedCode $node
+     */
+    foreach ($result as $i => $node) {
+        if ($node->getInfo() !== 'php') {
+            $node->setLiteral(trim($node->getLiteral()));
+            continue;
+        }
+
+        $targetPath = $targetDir . '/' . $fileName . '_' . $i . '.php';
+
+        if (!file_exists($targetPath)) {
+            $node->setLiteral(trim($node->getLiteral()));
+            continue;
+        }
+
+        $code = file_get_contents($targetPath);
+
+        $lines = explode("\n", $code);
+        array_splice($lines, 0, 2);
+        $code = implode("\n", $lines);
+
+        $node->setLiteral(trim($code));
+    }
+
+    file_put_contents($file->getPathname(), $markdownRenderer->renderDocument($document));
+}
+
+if (file_exists($targetDir)) {
+    exec('rm -rf ' . $targetDir);
+}

composer.json

@@ -32,6 +32,7 @@
     "ext-pdo_sqlite": "*",
     "doctrine/migrations": "^3.3.2",
     "infection/infection": "^0.27.0",
+    "league/commonmark": "^2.4",
     "patchlevel/coding-standard": "^1.3.0",
     "phpspec/prophecy-phpunit": "^2.1.0",
     "phpstan/phpstan": "^1.10.48",
@@ -41,7 +42,8 @@
     "symfony/uid": "^6.4.0|^7.0.0",
     "symfony/var-dumper": "^6.4.0|^7.0.0",
     "symfony/web-profiler-bundle": "^6.4.0|^7.0.0",
-    "vimeo/psalm": "^5.17.0"
+    "vimeo/psalm": "^5.17.0",
+    "wnx/commonmark-markdown-renderer": "^1.4"
   },
   "suggest": {
     "patchlevel/event-sourcing-admin-bundle": "for admin ui",