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.

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

Document how to use phpDocumentor as github action #2242

Open
jaapio opened this issue Jan 31, 2020 · 6 comments · May be fixed by #3695
Open

Document how to use phpDocumentor as github action #2242

jaapio opened this issue Jan 31, 2020 · 6 comments · May be fixed by #3695

Comments

@jaapio
Copy link
Member

jaapio commented Jan 31, 2020

In phpDocumentor's master branch a action.yml has been added. This opens new doors for projects to use phpDocumentor in their github workflows. The action is a currently a minimal setup. But no docs are available.

We should add a page in our cookbook to explain how to use phpDocumentor in github actions.

@rjindael
Copy link

@jaapio Hi, will this be added soon?

@andretefras
Copy link

@jaapio Hello, there is a minimal how to anywhere?

@thomascorthals
Copy link
Contributor

A how-to would be much appreciated!

I've tried to get this minimal example working:

name: Run Tests

on:
    push:

jobs:
    run-tests:
        runs-on: ubuntu-latest

        strategy:
            matrix:
                php: [7.4]

        name: PHP ${{ matrix.php }}

        steps:
            - name: Setup PHP
              uses: shivammathur/setup-php@v2
              with:
                php-version: ${{ matrix.php }}

            - name: Checkout repository
              uses: actions/checkout@v2

            - name: Generate API docs
              uses: phpDocumentor/phpDocumentor@master
              with:
                args: -d src -t build/docs

It does run on my local machine with nektos/act, but it fails when I push it to Github.

Current runner version: '2.285.1'
▸ Operating System
▸ Virtual Environment
▸ Virtual Environment Provisioner
▸ GITHUB_TOKEN Permissions
Secret source: Actions
Prepare workflow directory
Prepare all required actions
Getting action download info
Download action repository 'shivammathur/setup-php@v2' (SHA:15b20027cf4e61cb21f2582a8f125cafb1c0492e)
Download action repository 'actions/checkout@v2' (SHA:ec3a7ce113134d7a93b817d10a8272cb61118579)
Download action repository 'phpDocumentor/phpDocumentor@master' (SHA:765c4dd50a0a1a425b6c3b8415d6b3f5e7c45df5)
Error: Could not find file '/home/runner/work/_actions/_temp_7b9dfe7a-b180-4190-9ff4-1d0b6474174f/_staging/phpDocumentor-phpDocumentor-765c4dd/bin/php-parse'.

@ryomo
Copy link

ryomo commented Feb 22, 2022

Hi, here is a minimal example 😄

name: phpDocumentor

on:
  push:
    branches: [ main ]

jobs:
  phpdoc:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Run phpdoc
        run: |
          docker run --rm -v $(pwd):/data phpdoc/phpdoc:3 -d ./Src -t ./Docs

      - name: git commit
        run: |
          git config user.name "GitHub Actions"
          git config user.email ""
          git add Docs/
          git commit -m "Update phpdoc" || echo "No changes to commit"
          git push

@lkrms
Copy link

lkrms commented Aug 18, 2022

It took me so long to figure this out that I can't really justify writing it all up right now, but here's another solution (using parts of @ryomo's example above) that builds this repo into this GitHub Pages site whenever there's a commit to main. You should be able to use it without even needing to explicitly enable GitHub Pages for the repo (the actions theoretically do this for you, but I haven't tested it).

It also persists phpDocumentor's cache directory between runs, which might help with larger repos.

name: documentation

on:
  push:
    branches: [main]

  # Allow running the workflow manually from the Actions tab
  #workflow_dispatch:

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

# Allow one concurrent deployment
concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Configure GitHub Pages
        uses: actions/configure-pages@v1
      - name: Cache phpDocumentor build files
        id: phpdocumentor-cache
        uses: actions/cache@v3
        with:
          path: .phpdoc/cache
          key: ${{ runner.os }}-phpdocumentor-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-phpdocumentor-
      - name: Build with phpDocumentor
        run: docker run --rm --volume "$(pwd):/data" phpdoc/phpdoc:3 -vv --target docs --cache-folder .phpdoc/cache --template default
      - name: Upload artifact to GitHub Pages
        uses: actions/upload-pages-artifact@v1
        with:
          path: docs

  deploy:
    needs: build
    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@v1

@fulldecent fulldecent linked a pull request Apr 10, 2024 that will close this issue
@fulldecent
Copy link
Contributor

fulldecent commented Apr 10, 2024

Fix added at #3695

Includes practical stuff and links to documentation. Should be good enough to merge today and improve tomorrow.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
phpDoc issue triage board
  
Needs triage
Development

Successfully merging a pull request may close this issue.

7 participants