Refactor documentation and add gh-pages workflow (#1084)

Here goes...

.github/workflows/gh-pages.yml

@@ -0,0 +1,28 @@
+name: gh-pages
+
+on:
+  workflow_dispatch
+
+jobs:
+  gh-pages:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install vitepress
+        run: cd docs && npm install vitepress
+
+      - name: Build site
+        run: cd docs && npm run build
+
+      - name: Deploy to GitHub Pages
+        if: success()
+        uses: crazy-max/ghaction-github-pages@v2
+        with:
+          target_branch: gh-pages
+          build_dir: docs/.vitepress/dist
+          dry_run: true
+          verbose: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -5,7 +5,5 @@ bin/
 composer.lock
 docs/.vitepress/dist/
 docs/node_modules/
-local/
-openapi.json
-openapi.yaml
+docs/package-lock.json
 vendor/

Examples/using-links-php81/Repository.php

@@ -14,9 +14,6 @@ class Repository
     #[OAT\Property(type: 'string')]
     public $slug;
 
-    /**
-     * @var User
-     */
-    #[OAT\Property(ref: '#/components/schemas/user')]
-    public $owner;
+    #[OAT\Property()]
+    public User $owner;
 }

README.md

@@ -108,7 +108,7 @@ docker run -v "$PWD":/app -it tico/swagger-php --help
 - https://www.openapis.org
 - [OpenApi Documentation](https://swagger.io/docs/)
 - [OpenApi Specification](http://swagger.io/specification/)
-- [Related projects](docs/Related-projects.md)
+- [Related projects](docs/related-projects.md)
 
 ## Contributing
 

composer.json

@@ -62,6 +62,9 @@
     "phpunit/phpunit": ">=8"
   },
   "autoload-dev": {
+    "exclude-from-classmap": [
+      "/tests/Fixtures"
+    ],
     "psr-4": {
       "OpenApi\\Tests\\": "tests/",
       "AnotherNamespace\\": "tests/Fixtures/AnotherNamespace",
@@ -80,7 +83,8 @@
       "psalm --show-info=true"
     ],
     "spectral": "for ff in `find Examples -name *.yaml`; do spectral lint $ff; done",
-    "docs": "./docs/node_modules/.bin/vuepress dev docs/",
-    "deploy_docs": "./docs/node_modules/.bin/vuepress build docs/ && cp -r .git docs/.vuepress/dist/.git && cd docs/.vuepress/dist/ && git symbolic-ref HEAD refs/heads/gh-pages && git add --all"
+    "docs:dev": "cd docs && npm run dev",
+    "docs:build": "cd docs && npm run build",
+    "docs:deploy": "cd docs && npm run deploy"
   }
 }

docs/.vitepress/config.js

@@ -1,22 +1,81 @@
+function getGuideSidebar() {
+  return [
+    {
+      text: 'Introduction',
+      children: [
+        { text: 'What is Swagger-PHP?', link: '/guide/' },
+        { text: 'Installation', link: '/guide/installation' },
+        { text: 'Generating OpenAPI documents', link: '/guide/generating-openapi-documents' },
+      ]
+    },
+    {
+      text: 'Annotating your code',
+      children: [
+        { text: 'Attributes', link: '/guide/attributes' },
+        { text: 'Annotations', link: '/guide/annotations' },
+        { text: 'Required elements', link: '/guide/required-elements' },
+        { text: 'Common techniques', link: '/guide/common-techniques' },
+      ]
+    },
+    {
+      text: 'Upgrading',
+      children: [
+        { text: 'Migration from 3.x to 4.x', link: '/guide/migrating-to-v4' },
+        { text: 'Migration from 2.x to 3.x', link: '/guide/migrating-to-v3' },
+      ]
+    },
+    {
+      text: 'Other',
+      children: [
+        { text: 'Cookbook', link: '/guide/cookbook' },
+        { text: 'Under the hood', link: '/guide/under-the-hood' },
+        { text: 'Related Projects', link: '/related-projects' },
+      ]
+    },
+  ]
+}
+
+function getReferenceSidebar() {
+  return [
+    {
+      text: 'Reference',
+      children: [
+        { text: 'Attributes', link: '/reference/attributes' },
+        { text: 'Annotations', link: '/reference/annotations' },
+      ]
+    },
+    {
+      text: 'Api',
+      children: [
+        { text: 'Generator', link: '/reference/generator' },
+        { text: 'Processors', link: '/reference/processors' },
+      ]
+    },
+  ]
+}
+
+
 module.exports = {
   title: "Swagger-PHP",
   base: "/swagger-php/",
-  description:
-    "Generate OpenAPI documentation for your RESTful API using attributes or annotations.",
+  description: "Generate OpenAPI documentation for your RESTful API.",
   themeConfig: {
-    sidebar: "auto",
+    repo: 'zircote/swagger-php',
+    docsDir: 'docs',
+    docsBranch: 'master',
+    editLinks: false,
+    editLinkText: 'Edit this page on GitHub',
+
     nav: [
-      { text: "Guide", link: "/Getting-started" },
-      { text: "Supported Annotations", link: "/Supported-annotations" },
-      {
-        text: "OpenApi",
-        link: "https://swagger.io/docs/specification/about/"
-      },
-      {
-        text: "Specification",
-        link: "http://swagger.io/specification/"
-      },
-      { text: "Github", link: "https://github.com/zircote/swagger-php" },
-    ]
+      { text: "User Guide", link: "/guide/" },
+      { text: "Reference", link: "/reference/" },
+      { text: "OpenApi", link: "https://oai.github.io/Documentation/" },
+      { text: "Releases", link: "https://github.com/zircote/swagger-php/releases" },
+    ],
+
+    sidebar: {
+      '/guide/': getGuideSidebar(),
+      '/reference/': getReferenceSidebar()
+    }
   }
 };