Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document how to use with GitHub Actions #3695

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document how to use with GitHub Actions #3695

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
88 changes: 87 additions & 1 deletion docs/guides/continuous-integration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,93 @@ continuous integration services.
GitHub Actions
==============

<to be written>
Here is a working starting point to deploy phpDocs to your GitHub Pages for a project. You may also want
to update this to handle multiple versions of your project instead of just the latest.

.. code-block:: yaml

name: Generate phpDoc

# Allow GITHUB_TOKEN to deploy to GitHub Pages
permissions:
contents: read
pages: write
id-token: write

on:
workflow_dispatch: # Allow to manually deploy
push:
branches: ["main"]

jobs:
build:
runs-on: ubuntu-latest
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
steps:
- name: Checkout source code
uses: actions/checkout@v4
with:
path: source

# Install phpDocumentator using PHIVE
# phpDocumentator recommends PHIVE as the preferred install strategy
# Source: https://github.com/phpDocumentor/phpDocumentor/blob/919d5c1ef42a3c74d050e05ce99add6efa87b5a4/README.md?plain=1#L79
- name: Cache PHIVE tools
uses: actions/cache@v4
with:
path: ${{ runner.temp }}/.phive
key: php-phive-${{ hashFiles('.phive/phars.xml') }}
restore-keys: php-phive-

- name: Install PHIVE
uses: szepeviktor/phive@v1
with:
home: ${{ runner.temp }}/.phive
binPath: ${{ github.workspace }}/tools/phive

# TODO: confirm this is the correct GPG key
# Blocker: https://github.com/phpDocumentor/phpDocumentor/issues/3694
- name: Install phpDocumentor
run: ${{ github.workspace }}/tools/phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42

- name: Cache phpDocumentor build files
id: phpdocumentor-cache
uses: actions/cache@v4
with:
path: phpdoc-cache
key: ${{ runner.os }}-phpdocumentor-${{ github.sha }}
restore-keys: ${{ runner.os }}-phpdocumentor-

# Notice: -d xdebug.mode=off is required due to a bug/workaround
# Issue: https://github.com/phpDocumentor/phpDocumentor/issues/3642#issuecomment-1912354577
- name: Build with phpDocumentor
run: php -d xdebug.mode=off ${{ github.workspace }}/tools/phpDocumentor run -vv -d source --target docs --cache-folder phpdoc-cache --template default
Comment on lines +74 to +75
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

phpDocumentor provides a github action from this repository: https://github.com/phpDocumentor/phpDocumentor/blob/master/action.yml

      - name: "Build"
        uses: "phpDocumentor/phpDocumentor@master"
        with:
          target: "build/docs"

I think this is a better way of running since we can pack every dependency we need in a docker image. So people do not have to care about installing php correctly.


- name: Upload artifact to GitHub Pages
uses: actions/upload-pages-artifact@v3
with:
path: docs

deploy:
needs: build

# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
permissions:
pages: write # to deploy to Pages
id-token: write # to verify the deployment originates from an appropriate source

# Deploy to the github-pages environment
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}

runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

GitLab-ci
=========
Expand Down