Merge pull request #10815 from greg0ire/test-docs

greg0ire · web-flow · commit d6f4834476a2 · 2023-07-05T10:01:37.000+02:00
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,47 @@
+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@v3"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.2"
+
+      - name: "Remove existing composer file"
+        run: "rm composer.json"
+
+      - name: "Require phpdocumentor/guides-cli"
+        run: "composer require --dev phpdocumentor/guides-cli dev-main@dev --no-update"
+
+      - name: "Configure minimum stability"
+        run: "composer config minimum-stability dev"
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v2"
+        with:
+          dependency-versions: "highest"
+
+      - name: "Run guides-cli"
+        run: "vendor/bin/guides -vvv --no-progress docs/en /tmp/test 2>&1 | ( ! grep WARNING )"
diff --git a/docs/en/index.rst b/docs/en/index.rst
@@ -34,32 +34,32 @@ Mapping Objects onto a Database
 -------------------------------
 
 * **Mapping**:
-  :doc:`Objects <reference/basic-mapping>` |
-  :doc:`Associations <reference/association-mapping>` |
+  :doc:`Objects <reference/basic-mapping>` \|
+  :doc:`Associations <reference/association-mapping>` \|
   :doc:`Inheritance <reference/inheritance-mapping>`
 
 * **Drivers**:
-  :doc:`Docblock Annotations <reference/annotations-reference>` |
-  :doc:`Attributes <reference/attributes-reference>` |
-  :doc:`XML <reference/xml-mapping>` |
-  :doc:`YAML <reference/yaml-mapping>` |
+  :doc:`Docblock Annotations <reference/annotations-reference>` \|
+  :doc:`Attributes <reference/attributes-reference>` \|
+  :doc:`XML <reference/xml-mapping>` \|
+  :doc:`YAML <reference/yaml-mapping>` \|
   :doc:`PHP <reference/php-mapping>`
 
 Working with Objects
 --------------------
 
 * **Basic Reference**:
-  :doc:`Entities <reference/working-with-objects>` |
-  :doc:`Associations <reference/working-with-associations>` |
+  :doc:`Entities <reference/working-with-objects>` \|
+  :doc:`Associations <reference/working-with-associations>` \|
   :doc:`Events <reference/events>`
 
 * **Query Reference**:
-  :doc:`DQL <reference/dql-doctrine-query-language>` |
-  :doc:`QueryBuilder <reference/query-builder>` |
+  :doc:`DQL <reference/dql-doctrine-query-language>` \|
+  :doc:`QueryBuilder <reference/query-builder>` \|
   :doc:`Native SQL <reference/native-sql>`
 
 * **Internals**:
-  :doc:`Internals explained <reference/unitofwork>` |
+  :doc:`Internals explained <reference/unitofwork>` \|
   :doc:`Associations <reference/unitofwork-associations>`
 
 Advanced Topics
@@ -102,20 +102,20 @@ Cookbook
 --------
 
 * **Patterns**:
-  :doc:`Aggregate Fields <cookbook/aggregate-fields>` |
-  :doc:`Decorator Pattern <cookbook/decorator-pattern>` |
+  :doc:`Aggregate Fields <cookbook/aggregate-fields>` \|
+  :doc:`Decorator Pattern <cookbook/decorator-pattern>` \|
   :doc:`Strategy Pattern <cookbook/strategy-cookbook-introduction>`
 
 * **DQL Extension Points**:
-  :doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` |
+  :doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` \|
   :doc:`DQL User-Defined-Functions <cookbook/dql-user-defined-functions>`
 
 * **Implementation**:
-  :doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` |
-  :doc:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` |
-  :doc:`Working with DateTime <cookbook/working-with-datetime>` |
-  :doc:`Validation <cookbook/validation-of-entities>` |
-  :doc:`Entities in the Session <cookbook/entities-in-session>` |
+  :doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` \|
+  :doc:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` \|
+  :doc:`Working with DateTime <cookbook/working-with-datetime>` \|
+  :doc:`Validation <cookbook/validation-of-entities>` \|
+  :doc:`Entities in the Session <cookbook/entities-in-session>` \|
   :doc:`Keeping your Modules independent <cookbook/resolve-target-entity-listener>`
 
 * **Hidden Gems**
diff --git a/docs/en/reference/architecture.rst b/docs/en/reference/architecture.rst
@@ -102,7 +102,7 @@ persistent entity state and mapping information for its subclasses,
 but which is not itself an entity.
 
 Mapped superclasses are explained in greater detail in the chapter
-on :doc:`inheritance mapping <reference/inheritance-mapping>`.
+on :doc:`inheritance mapping </reference/inheritance-mapping>`.
 
 Transient Classes
 ~~~~~~~~~~~~~~~~~
diff --git a/docs/en/reference/basic-mapping.rst b/docs/en/reference/basic-mapping.rst
@@ -460,7 +460,7 @@ Here is the list of possible generation strategies:
    a new entity is passed to ``EntityManager#persist``. NONE is the
    same as leaving off the ``#[GeneratedValue]`` entirely.
 -  ``CUSTOM``: With this option, you can use the ``#[CustomIdGenerator]`` attribute.
-   It will allow you to pass a :doc:`class of your own to generate the identifiers.<_annref_customidgenerator>`
+   It will allow you to pass a :ref:`class of your own to generate the identifiers.<annref_customidgenerator>`
 
 Sequence Generator
 ^^^^^^^^^^^^^^^^^^
diff --git a/docs/en/reference/configuration.rst b/docs/en/reference/configuration.rst
@@ -104,7 +104,7 @@ Inside the ``ORMSetup`` methods several assumptions are made:
     In order to have ``ORMSetup`` configure the cache automatically, the library ``symfony/cache``
     has to be installed as a dependency.
 
-If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration <reference/advanced-configuration>` section.
+If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration </reference/advanced-configuration>` section.
 
 .. note::
 
diff --git a/docs/en/reference/dql-doctrine-query-language.rst b/docs/en/reference/dql-doctrine-query-language.rst
@@ -1336,8 +1336,8 @@ There are situations when a query you want to execute returns a
 very large result-set that needs to be processed. All the
 previously described hydration modes completely load a result-set
 into memory which might not be feasible with large result sets. See
-the `Batch Processing <batch-processing.html>`_ section on details how
-to iterate large result sets.
+the :doc:`Batch Processing </reference/batch-processing>` section on
+details how to iterate large result sets.
 
 Functions
 ~~~~~~~~~
diff --git a/docs/en/reference/improving-performance.rst b/docs/en/reference/improving-performance.rst
@@ -91,7 +91,7 @@ Apply Best Practices
 A lot of the points mentioned in the Best Practices chapter will
 also positively affect the performance of Doctrine.
 
-See :doc:`Best Practices <reference/best-practices>`
+See :doc:`Best Practices </reference/best-practices>`
 
 Change Tracking policies
 ------------------------
diff --git a/docs/en/reference/inheritance-mapping.rst b/docs/en/reference/inheritance-mapping.rst
@@ -35,7 +35,7 @@ have to be used.
     superclass, since they require the "many" side to hold the foreign
     key.
 
-    It is, however, possible to use the :doc:`ResolveTargetEntityListener <cookbook/resolve-target-entity-listener>`
+    It is, however, possible to use the :doc:`ResolveTargetEntityListener </cookbook/resolve-target-entity-listener>`
     to replace references to a mapped superclass with an entity class at runtime.
     As long as there is only one entity subclass inheriting from the mapped
     superclass and all references to the mapped superclass are resolved to that
@@ -45,7 +45,7 @@ have to be used.
 .. warning::
 
     At least when using attributes or annotations to specify your mapping,
-    it _seems_ as if you could inherit from a base class that is neither
+    it *seems* as if you could inherit from a base class that is neither
     an entity nor a mapped superclass, but has properties with mapping configuration
     on them that would also be used in the inheriting class.
 
@@ -60,7 +60,7 @@ have to be used.
     You may be tempted to use traits to mix mapped fields or relationships
     into your entity classes to circumvent some of the limitations of
     mapped superclasses. Before doing that, please read the section on traits
-    in the :doc:`Limitations and Known Issues <reference/limitations-and-known-issues>` chapter.
+    in the :doc:`Limitations and Known Issues </reference/limitations-and-known-issues>` chapter.
 
 Example:
 
@@ -380,7 +380,7 @@ It is not supported to use overrides in entity inheritance scenarios.
 .. note::
 
     When using traits, make sure not to miss the warnings given in the
-    :doc:`Limitations and Known Issues<reference/limitations-and-known-issues>` chapter.
+    :doc:`Limitations and Known Issues</reference/limitations-and-known-issues>` chapter.
 
 
 Association Override
diff --git a/docs/en/reference/installation.rst b/docs/en/reference/installation.rst
@@ -1,4 +1,4 @@
 Installation
 ============
 
-The installation chapter has moved to :doc:`Installation and Configuration <reference/configuration>`_.
+The installation chapter has moved to :doc:`Installation and Configuration </reference/configuration>`.
diff --git a/docs/en/reference/limitations-and-known-issues.rst b/docs/en/reference/limitations-and-known-issues.rst
@@ -145,7 +145,7 @@ more than two years after the initial Doctrine 2 release and the time where
 core components were designed.
 
 In fact, this documentation mentions traits only in the context of
-:doc:`overriding field association mappings in subclasses <tutorials/override-field-association-mappings-in-subclasses>`.
+:doc:`overriding field association mappings in subclasses </tutorials/override-field-association-mappings-in-subclasses>`.
 Coverage of traits in test cases is practically nonexistent.
 
 Thus, you should at least be aware that when using traits in your entity and
@@ -162,7 +162,7 @@ that, some precedence and conflict resolution rules apply.
 
 When it comes to loading mapping configuration, the annotation and attribute drivers
 rely on PHP reflection to inspect class properties including their docblocks.
-As long as the results are consistent with what a solution _without_ traits would
+As long as the results are consistent with what a solution *without* traits would
 have produced, this is probably fine.
 
 However, to mention known limitations, it is currently not possible to use "class"
diff --git a/docs/en/tutorials/getting-started.rst b/docs/en/tutorials/getting-started.rst
@@ -102,8 +102,7 @@ Install Doctrine using the Composer Dependency Management tool, by calling:
 This will install the packages Doctrine Common, Doctrine DBAL, Doctrine ORM,
 into the ``vendor`` directory.
 
-Add the following directories:
-::
+Add the following directories::
 
     doctrine2-tutorial
     |-- config
