Validate documentation rst with phpdocumentor

doctrine · Jun 19, 2024 · 8cd3137 · 8cd3137
1 parent 98e2e1b
commit 8cd3137
Show file tree

Hide file tree

Showing 7 changed files with 53 additions and 5 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,44 @@
+name: "Documentation"
+
+on:
+  pull_request:
+    branches:
+      - "*.x"
+    paths:
+      - .github/workflows/documentation.yml
+      - docs/**
+  push:
+    branches:
+      - "*.x"
+    paths:
+      - .github/workflows/documentation.yml
+      - docs/**
+
+jobs:
+  validate-with-guides:
+    name: "Validate documentation with phpDocumentor/guides"
+    runs-on: "ubuntu-22.04"
+
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v4"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.3"
+
+      - name: "Remove existing composer file"
+        run: "rm composer.json"
+
+      - name: "Require phpdocumentor/guides-cli"
+        run: "composer require --dev phpdocumentor/guides-cli --no-update"
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v3"
+        with:
+          dependency-versions: "highest"
+
+      - name: "Run guides-cli"
+        run: "vendor/bin/guides -vvv --no-progress docs/en 2>&1 | grep -v 'No template found for rendering directive' | ( ! grep WARNING )"
diff --git a/docs/en/cookbook/implementing-array-access-for-domain-objects.rst b/docs/en/cookbook/implementing-array-access-for-domain-objects.rst
@@ -1,7 +1,7 @@
 Implementing ArrayAccess for Domain Objects
 ===========================================
 
-.. sectionauthor:: Roman Borschel ([email protected])
+.. sectionauthor:: Roman Borschel
 
 This recipe will show you how to implement ArrayAccess for your
 domain objects in order to allow more uniform access, for example

diff --git a/docs/en/cookbook/implementing-the-notify-changetracking-policy.rst b/docs/en/cookbook/implementing-the-notify-changetracking-policy.rst
@@ -1,7 +1,7 @@
 Implementing the Notify ChangeTracking Policy
 =============================================
 
-.. sectionauthor:: Roman Borschel ([email protected])
+.. sectionauthor:: Roman Borschel
 
 The NOTIFY change-tracking policy is the most effective
 change-tracking policy provided by Doctrine but it requires some

diff --git a/docs/en/cookbook/implementing-wakeup-or-clone.rst b/docs/en/cookbook/implementing-wakeup-or-clone.rst
@@ -1,7 +1,7 @@
 Implementing Wakeup or Clone
 ============================
 
-.. sectionauthor:: Roman Borschel ([email protected])
+.. sectionauthor:: Roman Borschel
 
 As explained in the
 :doc:`restrictions for document classes in the manual <../reference/architecture>`.

diff --git a/docs/en/cookbook/validation-of-documents.rst b/docs/en/cookbook/validation-of-documents.rst
@@ -4,7 +4,7 @@ Validation of Documents
 Validation of Documents - Application Side
 ------------------------------------------
 
-.. sectionauthor:: Benjamin Eberlei <[email protected]>
+.. sectionauthor:: Benjamin Eberlei
 
 Doctrine does not ship with any internal validators, the reason
 being that we think all the frameworks out there already ship with
@@ -135,7 +135,7 @@ Further readings: :doc:`Lifecycle Events <../reference/events>`
 Validation of Documents - Database Side
 ---------------------------------------
 
-.. sectionauthor:: Alexandre Abrioux <[email protected]>
+.. sectionauthor:: Alexandre Abrioux
 
 .. note::
 

diff --git a/docs/en/reference/custom-mapping-types.rst b/docs/en/reference/custom-mapping-types.rst
@@ -94,3 +94,6 @@ type in your mapping like this:
     .. code-block:: xml
 
         <field field-name="field" type="mytype" />
+
+.. |FQCN| raw:: html
+  <abbr title="Fully-Qualified Class Name">FQCN</abbr>
diff --git a/docs/en/sidebar.rst b/docs/en/sidebar.rst
@@ -1,3 +1,4 @@
+:orphan:
 .. toc::
 
     .. tocheader:: Tutorials