Merge pull request #6 from reload/README-refactor

README refactor

.github/dependabot.yml

@@ -15,4 +15,11 @@ updates:
       interval: daily
       timezone: Europe/Copenhagen
     reviewers:
-      - arnested"
+      - arnested
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: daily
+      timezone: Europe/Copenhagen
+    reviewers:
+      - arnested

.github/workflows/lint.yml

@@ -10,12 +10,14 @@ permissions:
 
 jobs:
   actionlint:
+    name: GitHub Actions
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
-      - uses: reviewdog/action-actionlint@v1
+      - name: Run actionlint
+        uses: reviewdog/action-actionlint@v1
   markdownlint:
-    name: markdown
+    name: Markdown
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
@@ -26,11 +28,27 @@ jobs:
             **/*.md
             !README.md
   yamllint:
-    name: Yamllint
+    name: YAML
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
-      - name: Run Yamllint
+      - name: Run yamllint
         uses: frenck/[email protected]
         with:
           strict: true
+  shellcheck:
+    name: Shell scripts
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run shellcheck
+        uses: ludeeus/[email protected]
+        env:
+          SHELLCHECK_OPTS: -o all
+  checkmake:
+    name: Makfile
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run checkmake
+        uses: Uno-Takashi/checkmake-action@main

.github/workflows/readme.yml

@@ -0,0 +1,40 @@
+---
+name: README
+on:
+  - pull_request
+  - push
+
+permissions:
+  contents: read
+
+jobs:
+  check-readme:
+    name: Check README.md is up-to-date
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          tools: composer
+          coverage: none
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> "${GITHUB_OUTPUT}"
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: Build README.md
+        run: |
+          make README.md
+      - name: Check README.md
+        run: |
+          git diff --exit-code README.md

Dockerfile

@@ -0,0 +1 @@
+FROM phpdoc/phpdoc:3@sha256:eede231f3f3f0308cfaba5dd39963c55b8912f4a7cacc81baa95b274c8736ae4

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test lint fix docs phpunit phpcs phpstan all install clean
+.PHONY: test lint fix phpunit phpcs phpstan all install clean
 
 export XDEBUG_MODE=coverage
 
@@ -8,11 +8,8 @@ lint: phpcs phpstan
 
 fix: phpcbf
 
-docs: src vendor
-	docker run --user=$(shell id -u) --rm -v ".:/data" "phpdoc/phpdoc:3"
-
-README.md: src docs
-	sed 's/\(__construct.*\): mixed/\1/' < docs/classes/Reload/Cpr/CprNumber.md | grep -v '\*\*\*' | grep -v 'Automatically generated on' | sed 's/(\.\/\(.*\)\.md)/(src\/\1.php)/' | cat -s > README.md
+README.md: vendor src bin/generate-readme.sh
+	bin/generate-readme.sh
 
 test: phpunit
 

bin/generate-readme.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+set -v
+
+PHPDOC_IMAGE_ID=$(docker build . 2>&1 >/dev/null | grep 'writing image' | cut -f 2 -d: | cut -f 1 -d ' ')
+
+# Build phpDoc in ./docs
+docker run --user="${UID}" --rm -v ".:/data" "${PHPDOC_IMAGE_ID}"
+
+# Build README.md from phpDocs CprNumber documentation
+(
+	# Fix phpDoc using mixed as return type of constructor
+	sed 's/\(__construct.*\): mixed/\1/' |
+		# Remove heavy horizontal lines
+		grep -v '\*\*\*' |
+		# Remove phpDoc "generated on" timestamp
+		grep -v 'Automatically generated on' |
+		# Fix links to phpDoc
+		sed 's/(\.\/\(.*\)\.md)/(src\/\1.php)/' |
+		# Remove empty lines
+		cat -s
+) <docs/classes/Reload/Cpr/CprNumber.md >README.md

phpdoc.dist.xml

@@ -10,16 +10,11 @@
   </paths>
   <version number="latest">
     <api>
-      <markers>
-        <marker>NOTICE</marker>
-      </markers>
       <visibility>public</visibility>
       <source dsn=".">
         <path>src/CprNumber.php</path>
       </source>
     </api>
   </version>
-  <template name="./vendor/saggre/phpdocumentor-markdown/themes/markdown">
-    <parameter name="urlFileExtensions" value="yes"/>
-  </template>
+  <template name="./vendor/saggre/phpdocumentor-markdown/themes/markdown"/>
 </phpdocumentor>