Add rendered documentation for website

Author: jaapio

.github/workflows/documentation.yaml

@@ -0,0 +1,61 @@
+name: "Documentation"
+
+on: # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - "6.x"
+  pull_request: null
+
+jobs:
+  documentation:
+    name: "Documentation"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v4"
+
+      - name: "Build"
+        uses: "phpDocumentor/phpDocumentor@master"
+
+      - name: "Deploy"
+        if: "${{ github.event_name == 'push' && github.ref == 'refs/heads/6.x' }}"
+        uses: "actions/upload-artifact@v4"
+        with:
+          name: "documentation"
+          path: "build/docs"
+          retention-days: 1
+
+  deploy:
+    name: "Deploy"
+    if: "${{ github.event_name == 'push' && github.ref == 'refs/heads/6.x' }}"
+    runs-on: "ubuntu-latest"
+    needs: "documentation"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v4"
+        with:
+          repository: "phpDocumentor/docs"
+          token: "${{ secrets.BOT_TOKEN }}"
+          path: "docs"
+
+      - name: "Download"
+        uses: "actions/download-artifact@v4"
+        with:
+          name: "documentation"
+          path: "build/docs"
+
+      - name: "Copy files"
+        run: "rsync -r --delete build/docs/* docs/docs/components/reflection"
+
+      - name: "Commit"
+        uses: "stefanzweifel/git-auto-commit-action@v5"
+        with:
+          repository: "docs"
+          commit_message: "Update reflection documentation"
+
+      - name: "Push"
+        uses: "ad-m/github-push-action@master"
+        with:
+          directory: "docs"
+          github_token: "${{ secrets.BOT_TOKEN }}"
+          repository: "phpDocumentor/docs"

.gitignore

@@ -17,3 +17,5 @@ vendor/
 phpunit.xml
 .phpunit.result.cache
 .phpunit.cache
+
+.phpdoc/cache

.phpdoc/template/base.html.twig

@@ -0,0 +1,15 @@
+{% extends 'layout.html.twig' %}
+
+{% set topMenu = {
+    "menu": [
+        { "name": "About", "url": "https://phpdoc.org/"},
+        { "name": "Components", "url": "https://phpdoc.org/components.html"},
+        { "name": "Documentation", "url": "https://docs.phpdoc.org/"},
+    ],
+    "social": [
+        { "iconClass": "fab fa-mastodon", "url": "https://phpc.social/@phpdoc"},
+        { "iconClass": "fab fa-github", "url": "https://github.com/phpdocumentor/typeresolver"},
+        { "iconClass": "fas fa-envelope-open-text", "url": "https://github.com/orgs/phpDocumentor/discussions"}
+    ]
+}
+%}

Makefile

@@ -11,9 +11,9 @@ fix-code-style:
 	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:8.1-cli vendor/bin/phpcbf
 
 .PHONY: static-code-analysis
-static-code-analysis: vendor ## Runs a static code analysis with phpstan/phpstan and vimeo/psalm
+static-code-analysis: #vendor ## Runs a static code analysis with phpstan/phpstan and vimeo/psalm
 	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:8.2-cli vendor/bin/phpstan --configuration=phpstan.neon
-	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:8.2-cli vendor/bin/psalm.phar
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:8.2-cli vendor/bin/psalm.phar --show-info=true --threads=4
 
 .PHONY: test
 test: test-unit test-functional ## Runs all test suites with phpunit/phpunit
@@ -45,3 +45,7 @@ rector: ## Refactor code using rector
 
 .PHONY: pre-commit-test
 pre-commit-test: fix-code-style test code-style static-code-analysis
+
+.PHONY: docs
+docs: ## Generate documentation
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpdoc/phpdoc:3-unstable

README.md

@@ -37,7 +37,7 @@ are however several advantages to using this library:
 In order to inspect a codebase you need to tell composer to include the `phpdocumentor/reflection` package. This
 can easily be done using the following command in your command line terminal:
 
-    composer require phpdocumentor/reflection:~5.0
+    composer require phpdocumentor/reflection:~6.0
 
 After the installation is complete no further configuration is necessary and you can immediately start using it.
 

docs/extending/index.rst

@@ -0,0 +1,34 @@
+.. _extending:
+
+Extend the library
+==================
+
+The model exposed by this library is closed for inheritance. We did this to ensure the model is stable and does not
+change via external factors. The complexity of this project makes it hard to keep all the internal classes stable.
+The model is designed to be cached and constructed very carefully to ensure performance and memory usage are optimal.
+
+Metadata
+--------
+
+Metadata is a way to extend the model with additional information. We call this metadata, as all first class
+elements in the reflected codebase are part of the model. Extra data can be added to these elements using metadata.
+
+Elements supporting metadata are:
+
+.. phpdoc:class-list:: [?(@.interfaces contains "\phpDocumentor\Reflection\Metadata\MetaDataContainer")]
+
+   .. phpdoc:name::
+
+.. warning::
+
+    Adding metadata might break the posibilty to cache the model. Be carefull with circular references and large
+    objects. We do recommend to keep the metadata small and simple.
+
+Continue reading :doc:`Creating your first metadata <meta-data>`_ to learn how to create your own metadata.
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :hidden:
+
+   meta-data

docs/meta-data.rst renamed to docs/extending/meta-data.rst

@@ -0,0 +1,49 @@
+Getting started
+===============
+
+This page will give you a quick introduction to the `phpdocumentor/reflection` package and how to get started with it.
+
+Installation
+------------
+
+In order to inspect a codebase you need to tell composer to include the `phpdocumentor/reflection` package. This
+can easily be done using the following command in your command line terminal:
+
+.. code-block:: bash
+
+    composer require phpdocumentor/reflection:~6.0
+
+In order to use the library you need to include the autoloader of composer in your code.
+ This can be done by adding the following line to your code:
+
+.. code-block:: php
+
+    <?php
+    require_once 'vendor/autoload.php';
+
+After the installation is complete no further configuration is necessary and you can immediately start using it.
+
+Basic usage
+------------
+
+The :php:class:`\phpDocumentor\Reflection\Php\ProjectFactory` class is the entry point to the library and is used to create a new
+project object that contains all the information about your codebase. It is configured with sensible defaults. And for most
+usecases you can just use it as is.
+
+.. code-block:: php
+
+    $projectFactory = \phpDocumentor\Reflection\Php\ProjectFactory::createInstance();
+
+At this point we are ready to analyze your complete project or just one file at the time. Just pass an array of file paths to the `create` method of the project factory.
+
+.. code-block:: php
+
+    $projectFiles = [new \phpDocumentor\Reflection\File\LocalFile('tests/example.file.php')];
+    $project = $projectFactory->create('My Project', $projectFiles);
+
+When the process is ready a new object of type :php:class:`phpDocumentor\Reflection\Php\Project` will be returned that
+contains a complete hierarchy of all files with their classes, traits and interfaces (and everything in there), but also
+all namespaces and packages as a hierarchical tree.
+This library does not provide a way to access the structure of the codebase in a searchable way.
+This is up to the consumer of the library to implement.
+