feat: add docs generation action and fix docs (#1872)

bshaffer · web-flow · commit 8e9215910703 · 2020-07-10T09:32:24.000-07:00
diff --git a/.github/actions/docs/entrypoint.sh b/.github/actions/docs/entrypoint.sh
@@ -0,0 +1,21 @@
+#!/bin/sh -l
+
+apt-get update
+apt-get install -y git
+git reset --hard HEAD
+
+# Required so sami.php is available for previous versions
+cp .github/actions/docs/sami.php.dist .github/actions/docs/sami.php
+
+# Run the docs generation command
+php vendor/bin/sami.php update .github/actions/docs/sami.php
+
+cd ./.docs
+
+git init
+git config user.name "GitHub Actions"
+git config user.email "actions@github.com"
+
+git add .
+git commit -m "Updating docs"
+git push -q https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/${GITHUB_REPOSITORY} HEAD:gh-pages --force
diff --git a/.github/actions/docs/sami.php b/.github/actions/docs/sami.php
@@ -0,0 +1,29 @@
+<?php
+
+use Sami\RemoteRepository\GitHubRemoteRepository;
+use Sami\Sami;
+use Sami\Version\GitVersionCollection;
+use Symfony\Component\Finder\Finder;
+
+$projectRoot = __DIR__ . '/../../..';
+
+$iterator = Finder::create()
+    ->files()
+    ->name('*.php')
+    ->exclude('vendor')
+    ->exclude('tests')
+    ->in($projectRoot);
+
+$versions = GitVersionCollection::create($projectRoot)
+    ->addFromTags(function($tag) {
+        return 0 === strpos($tag, 'v2.') && false === strpos($tag, 'RC');
+    })
+    ->add('master', 'master branch');
+
+return new Sami($iterator, [
+    'title' => 'Google APIs Client Library for PHP API Reference',
+    'build_dir' => $projectRoot . '/.docs/%version%',
+    'cache_dir' => $projectRoot . '/.cache/%version%',
+    'remote_repository' => new GitHubRemoteRepository('googleapis/google-api-php-client', $projectRoot),
+    'versions' => $versions
+]);
diff --git a/.github/actions/docs/sami.php.dist b/.github/actions/docs/sami.php.dist
@@ -0,0 +1,29 @@
+<?php
+
+use Sami\RemoteRepository\GitHubRemoteRepository;
+use Sami\Sami;
+use Sami\Version\GitVersionCollection;
+use Symfony\Component\Finder\Finder;
+
+$projectRoot = __DIR__ . '/../../..';
+
+$iterator = Finder::create()
+    ->files()
+    ->name('*.php')
+    ->exclude('vendor')
+    ->exclude('tests')
+    ->in($projectRoot);
+
+$versions = GitVersionCollection::create($projectRoot)
+    ->addFromTags(function($tag) {
+        return 0 === strpos($tag, 'v2.') && false === strpos($tag, 'RC');
+    })
+    ->add('master', 'master branch');
+
+return new Sami($iterator, [
+    'title' => 'Google APIs Client Library for PHP API Reference',
+    'build_dir' => $projectRoot . '/.docs/%version%',
+    'cache_dir' => $projectRoot . '/.cache/%version%',
+    'remote_repository' => new GitHubRemoteRepository('googleapis/google-api-php-client', $projectRoot),
+    'versions' => $versions
+]);
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,28 @@
+name: Generate Documentation
+on:
+    push:
+        branches:
+            - master
+        tags:
+            - "*"
+
+jobs:
+    docs:
+        name: "Generate Project Documentation"
+        runs-on: ubuntu-16.04
+        steps:
+        - name: Checkout
+          uses: actions/checkout@v2
+        - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+        - name: Install Dependencies
+          uses: nick-invision/retry@v1
+          with:
+            timeout_minutes: 10
+            max_attempts: 3
+            command: composer config repositories.sami vcs https://${{ secrets.GITHUB_TOKEN }}@github.com/jdpedrie/sami.git && composer require sami/sami:dev-master && git reset --hard HEAD
+        - name: Generate and Push Documentation
+          uses: docker://php:7.3-cli
+          env:
+            GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          with:
+            entrypoint: ./.github/actions/docs/entrypoint.sh
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 .DS_Store
+.github/actions/docs/sami.php
 phpunit.xml
 phpcs.xml
 composer.lock
diff --git a/src/Google/AccessToken/Verify.php b/src/Google/AccessToken/Verify.php
@@ -73,7 +73,8 @@ public function __construct(
    * The audience parameter can be used to control which id tokens are
    * accepted.  By default, the id token must have been issued to this OAuth2 client.
    *
-   * @param $audience
+   * @param string $idToken the ID token in JWT format
+   * @param string $audience Optional. The audience to verify against JWt "aud"
    * @return array the token payload, if successful
    */
   public function verifyIdToken($idToken, $audience = null)
diff --git a/src/Google/Client.php b/src/Google/Client.php
@@ -765,8 +765,11 @@ public function verifyIdToken($idToken = null)
   /**
    * Set the scopes to be requested. Must be called before createAuthUrl().
    * Will remove any previously configured scopes.
-   * @param string|array $scope_or_scopes, ie: array('https://www.googleapis.com/auth/plus.login',
-   * 'https://www.googleapis.com/auth/moderator')
+   * @param string|array $scope_or_scopes, ie:
+   *    array(
+   *        'https://www.googleapis.com/auth/plus.login',
+   *        'https://www.googleapis.com/auth/moderator'
+   *    );
    */
   public function setScopes($scope_or_scopes)
   {
@@ -819,6 +822,7 @@ public function prepareScopes()
    * Helper method to execute deferred HTTP requests.
    *
    * @param $request Psr\Http\Message\RequestInterface|Google_Http_Batch
+   * @param string $expectedClass
    * @throws Google_Exception
    * @return object of the type of the expected class or Psr\Http\Message\ResponseInterface.
    */
diff --git a/src/Google/Http/MediaFileUpload.php b/src/Google/Http/MediaFileUpload.php
@@ -114,8 +114,8 @@ public function getProgress()
 
   /**
    * Send the next part of the file to upload.
-   * @param [$chunk] the next set of bytes to send. If false will used $data passed
-   * at construct time.
+   * @param bool $chunk Optional. The next set of bytes to send. If false will
+   * use $data passed at construct time.
    */
   public function nextChunk($chunk = false)
   {
diff --git a/src/Google/Http/REST.php b/src/Google/Http/REST.php
@@ -33,6 +33,9 @@ class Google_Http_REST
    *
    * @param Google_Client $client
    * @param Psr\Http\Message\RequestInterface $req
+   * @param string $expectedClass
+   * @param array $config
+   * @param array $retryMap
    * @return array decoded result
    * @throws Google_Service_Exception on server side error (ie: not authenticated,
    *  invalid or malformed post body, invalid url)
@@ -63,6 +66,7 @@ public static function execute(
    *
    * @param Google_Client $client
    * @param Psr\Http\Message\RequestInterface $request
+   * @param string $expectedClass
    * @return array decoded result
    * @throws Google_Service_Exception on server side error (ie: not authenticated,
    *  invalid or malformed post body, invalid url)
@@ -100,6 +104,7 @@ public static function doExecute(ClientInterface $client, RequestInterface $requ
    * @throws Google_Service_Exception
    * @param Psr\Http\Message\RequestInterface $response The http response to be decoded.
    * @param Psr\Http\Message\ResponseInterface $response
+   * @param string $expectedClass
    * @return mixed|null
    */
   public static function decodeHttpResponse(
diff --git a/src/Google/Service/Exception.php b/src/Google/Service/Exception.php
@@ -31,7 +31,6 @@ class Google_Service_Exception extends Google_Exception
    * @param Exception|null $previous
    * @param [{string, string}] errors List of errors returned in an HTTP
    * response.  Defaults to [].
-   * @param array|null $retryMap Map of errors with retry counts.
    */
   public function __construct(
       $message,

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`.DS_Store`
	`2`	`+.github/actions/docs/sami.php`
`2`	`3`	`phpunit.xml`
`3`	`4`	`phpcs.xml`
`4`	`5`	`composer.lock`