Merge pull request #12216 from paulinevos/docs-builder

Use docs builder in ORM repo

Author: greg0ire

.github/workflows/documentation.yml

@@ -17,4 +17,4 @@ on:
 jobs:
   documentation:
     name: "Documentation"
-    uses: "doctrine/.github/.github/workflows/documentation.yml@10.1.0"
+    uses: "doctrine/.github/.github/workflows/documentation.yml@12.0.0"

composer.json

@@ -12,6 +12,9 @@
         {"name": "Jonathan Wage", "email": "[email protected]"},
         {"name": "Marco Pivetta", "email": "[email protected]"}
     ],
+    "scripts": {
+        "docs": "composer --working-dir docs update && ./docs/vendor/bin/build-docs.sh @additional_args"
+    },
     "config": {
         "allow-plugins": {
             "composer/package-versions-deprecated": true,

docs/.gitignore

@@ -1,3 +1,3 @@
 composer.lock
 vendor/
-build/
+output/

docs/Makefile

@@ -4,19 +4,15 @@ The documentation is written in [ReStructured Text](https://docutils.sourceforge
 
 ## How to Generate:
 
-In the `docs/` folder, run
+In the project root, run
 
-    composer update
+    composer docs
 
-Then compile the documentation with:
-
-    make html
-
-This will generate the documentation into the `build` subdirectory.
+This will generate the documentation into the `docs/output` subdirectory.
 
 To browse the documentation, you need to run a webserver:
 
-    cd build/html
+    cd docs/output
     php -S localhost:8000
 
 Now the documentation is available at [http://localhost:8000](http://localhost:8000).

docs/README.md

@@ -3,8 +3,7 @@
     "description": "Documentation for the Object-Relational Mapper\"",
     "type": "library",
     "license": "MIT",
-    "require": {
-        "phpdocumentor/guides-cli": "1.7.1",
-        "phpdocumentor/filesystem": "1.7.1"
+    "require-dev": {
+        "doctrine/docs-builder": "^1.0"
     }
 }

docs/composer.json

@@ -61,6 +61,7 @@ class GH12174Smurf
      * @ORM\Id
      * @ORM\GeneratedValue
      * @ORM\Column(type="integer")
+     *
      * @var int
      */
     #[ORM\Id]
@@ -70,13 +71,15 @@ class GH12174Smurf
 
     /**
      * @ORM\ManyToOne(inversedBy="children", targetEntity="GH12174Smurf")
+     *
      * @var GH12174Smurf
      */
     #[ManyToOne(inversedBy: 'children')]
     private $parent;
 
     /**
      * @ORM\OneToMany(targetEntity="GH12174Smurf", mappedBy="parent")
+     *
      * @var Collection
      */
     #[OneToMany(targetEntity: self::class, mappedBy: 'parent')]