feat(doc): improve builders documentation

sensiolabs · Jul 18, 2024 · fb01847 · fb01847
1 parent cb17959
commit fb01847
Show file tree

Hide file tree

Showing 20 changed files with 829 additions and 92 deletions.
diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
@@ -0,0 +1,38 @@
+name: 'Documentation'
+
+on:
+  push:
+    branches: ['main']
+  pull_request:
+    branches: ['main']
+
+permissions:
+  contents: 'read'
+
+jobs:
+
+  builders-api:
+    name: 'Builders API'
+    runs-on: 'ubuntu-latest'
+    steps:
+      - uses: 'actions/checkout@v4'
+
+      - name: 'Setup PHP'
+        uses: 'shivammathur/setup-php@v2'
+        with:
+          php-version: '8.3'
+          coverage: 'none'
+
+      - name: 'Install dependencies'
+        uses: 'ramsey/composer-install@v3'
+
+      - name: 'Generate builder API doc'
+        run: 'php ./docs/generate.php'
+
+      - name: 'Check documentation'
+        run: |
+          if [[ $(git diff --name-only | wc -l) > 0 ]]; then
+            echo "::error::Builders API documentation is not up to date, please run \"php ./docs/generate.php\""
+            exit 1
+          fi
+
diff --git a/README.md b/README.md
@@ -208,6 +208,7 @@ class YourController
 
 1. [Configuration](./docs/configuration.md)
 2. [Working with assets](./docs/assets.md)
+3. [Builders API](./docs/builders_api.md)
 
 #### PDF
 

diff --git a/docs/Builders.md b/docs/Builders.md
diff --git a/docs/builders_api.md b/docs/builders_api.md
@@ -0,0 +1,15 @@
+# Builders API
+
+## Pdf
+
+* [HtmlPdfBuilder](./pdf/builders_api/HtmlPdfBuilder.md)
+* [UrlPdfBuilder](./pdf/builders_api/UrlPdfBuilder.md)
+* [MarkdownPdfBuilder](./pdf/builders_api/MarkdownPdfBuilder.md)
+* [LibreOfficePdfBuilder](./pdf/builders_api/LibreOfficePdfBuilder.md)
+
+## Screenshot
+
+* [HtmlScreenshotBuilder](./screenshot/builders_api/HtmlScreenshotBuilder.md)
+* [UrlScreenshotBuilder](./screenshot/builders_api/UrlScreenshotBuilder.md)
+* [MarkdownScreenshotBuilder](./screenshot/builders_api/MarkdownScreenshotBuilder.md)
+
diff --git a/docs/generate.php b/docs/generate.php
@@ -87,8 +87,7 @@ function parseBuilder(ReflectionClass $builder): string
     $markdown = '';
 
     $builderName = $builder->getShortName();
-    $markdown .= "{$builderName}\n";
-    $markdown .= str_repeat('=', \strlen($builderName))."\n\n";
+    $markdown .= "# {$builderName}\n\n";
 
     foreach ($builder->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
         if (\in_array($method->getName(), EXCLUDED_METHODS, true) === true) {
@@ -116,32 +115,29 @@ function saveFile(InputInterface $input, string $filename, string $contents): vo
 $application = new Application();
 $application->register('generate')
     ->setCode(function (InputInterface $input) {
-        $summary = <<<MARKDOWN
-        Builders
-        ========
-
-        MARKDOWN;
+        $summary = "# Builders API\n\n";
 
         foreach (BUILDERS as $type => $builderClasses) {
-            $directory = __DIR__."/{$type}";
+            $subDirectory = strtolower($type).'/builders_api';
+            $directory = __DIR__.'/'.$subDirectory;
 
             if (!@mkdir($directory, recursive: true) && !is_dir($directory)) {
                 throw new RuntimeException(sprintf('Directory "%s" was not created', $directory));
             }
 
-            $summary .= "# {$type}\n\n";
+            $summary .= "## {$type}\n\n";
 
             foreach ($builderClasses as $pdfBuilder) {
                 $reflectionClass = new ReflectionClass($pdfBuilder);
 
                 $markdown = parseBuilder($reflectionClass);
                 saveFile($input, "{$directory}/{$reflectionClass->getShortName()}.md", $markdown);
 
-                $summary .= "* [{$reflectionClass->getShortName()}](./{$type}/{$reflectionClass->getShortName()}.md)\n";
+                $summary .= "* [{$reflectionClass->getShortName()}](./{$subDirectory}/{$reflectionClass->getShortName()}.md)\n";
             }
             $summary .= "\n";
 
-            saveFile($input, __DIR__.'/Builders.md', $summary);
+            saveFile($input, __DIR__.'/builders_api.md', $summary);
         }
 
         return Command::SUCCESS;

diff --git a/docs/Pdf/HtmlPdfBuilder.md → docs/pdf/builders_api/HtmlPdfBuilder.md b/docs/Pdf/HtmlPdfBuilder.md → docs/pdf/builders_api/HtmlPdfBuilder.md
@@ -1,11 +1,16 @@
-HtmlPdfBuilder
-==============
+# HtmlPdfBuilder
 
 * `content(string $template, array $context)`:
 
 * `contentFile(string $path)`:
 The HTML file to convert into PDF.
 
+* `cookies(array $cookies)`:
+
+* `setCookie(string $key, Symfony\Component\HttpFoundation\Cookie|array $cookie)`:
+
+* `forwardCookie(string $name)`:
+
 * `singlePage(bool $bool)`:
 Define whether to print the entire content in one single page.
 If the singlePage form field is set to true, it automatically overrides the values from the paperHeight and nativePageRanges form fields.
@@ -89,14 +94,6 @@ For instance: "window.status === 'ready'".
 * `emulatedMediaType(Sensiolabs\GotenbergBundle\Enumeration\EmulatedMediaType $mediaType)`:
 Forces Chromium to emulate, either "screen" or "print". (default "print").
 
-* `cookies(array $cookies)`:
-Cookies to store in the Chromium cookie jar. (overrides any previous cookies).
-
-* `setCookie(string $key, array $cookie)`:
-
-* `addCookies(array $cookies)`:
-Add cookies to store in the Chromium cookie jar.
-
 * `extraHttpHeaders(array $headers)`:
 Sets extra HTTP headers that Chromium will send when loading the HTML
 document. (default None). (overrides any previous headers).
@@ -129,3 +126,8 @@ The metadata to write.
 
 * `fileName(string $fileName, string $headerDisposition)`:
 
+* `processor(Sensiolabs\GotenbergBundle\Processor\ProcessorInterface $processor)`:
+
+* `addCookies(array $cookies)`:
+Add cookies to store in the Chromium cookie jar.
+
diff --git a/docs/Pdf/LibreOfficePdfBuilder.md → ...pdf/builders_api/LibreOfficePdfBuilder.md b/docs/Pdf/LibreOfficePdfBuilder.md → ...pdf/builders_api/LibreOfficePdfBuilder.md
@@ -1,5 +1,4 @@
-LibreOfficePdfBuilder
-=====================
+# LibreOfficePdfBuilder
 
 * `landscape(bool $bool)`:
 Sets the paper orientation to landscape.
@@ -34,3 +33,5 @@ The metadata to write.
 
 * `fileName(string $fileName, string $headerDisposition)`:
 
+* `processor(Sensiolabs\GotenbergBundle\Processor\ProcessorInterface $processor)`:
+
diff --git a/docs/Pdf/MarkdownPdfBuilder.md → docs/pdf/builders_api/MarkdownPdfBuilder.md b/docs/Pdf/MarkdownPdfBuilder.md → docs/pdf/builders_api/MarkdownPdfBuilder.md
@@ -1,5 +1,4 @@
-MarkdownPdfBuilder
-==================
+# MarkdownPdfBuilder
 
 * `wrapper(string $template, array $context)`:
 The HTML file that wraps the markdown content, rendered from a Twig template.
@@ -9,6 +8,12 @@ The HTML file that wraps the markdown content.
 
 * `files(string $paths)`:
 
+* `cookies(array $cookies)`:
+
+* `setCookie(string $key, Symfony\Component\HttpFoundation\Cookie|array $cookie)`:
+
+* `forwardCookie(string $name)`:
+
 * `singlePage(bool $bool)`:
 Define whether to print the entire content in one single page.
 If the singlePage form field is set to true, it automatically overrides the values from the paperHeight and nativePageRanges form fields.
@@ -92,14 +97,6 @@ For instance: "window.status === 'ready'".
 * `emulatedMediaType(Sensiolabs\GotenbergBundle\Enumeration\EmulatedMediaType $mediaType)`:
 Forces Chromium to emulate, either "screen" or "print". (default "print").
 
-* `cookies(array $cookies)`:
-Cookies to store in the Chromium cookie jar. (overrides any previous cookies).
-
-* `setCookie(string $key, array $cookie)`:
-
-* `addCookies(array $cookies)`:
-Add cookies to store in the Chromium cookie jar.
-
 * `extraHttpHeaders(array $headers)`:
 Sets extra HTTP headers that Chromium will send when loading the HTML
 document. (default None). (overrides any previous headers).
@@ -132,3 +129,8 @@ The metadata to write.
 
 * `fileName(string $fileName, string $headerDisposition)`:
 
+* `processor(Sensiolabs\GotenbergBundle\Processor\ProcessorInterface $processor)`:
+
+* `addCookies(array $cookies)`:
+Add cookies to store in the Chromium cookie jar.
+
diff --git a/docs/Pdf/UrlPdfBuilder.md → docs/pdf/builders_api/UrlPdfBuilder.md b/docs/Pdf/UrlPdfBuilder.md → docs/pdf/builders_api/UrlPdfBuilder.md
@@ -1,5 +1,4 @@
-UrlPdfBuilder
-=============
+# UrlPdfBuilder
 
 * `setRequestContext(?Symfony\Component\Routing\RequestContext $requestContext)`:
 
@@ -8,6 +7,12 @@ URL of the page you want to convert into PDF.
 
 * `route(string $name, array $parameters)`:
 
+* `cookies(array $cookies)`:
+
+* `setCookie(string $key, Symfony\Component\HttpFoundation\Cookie|array $cookie)`:
+
+* `forwardCookie(string $name)`:
+
 * `singlePage(bool $bool)`:
 Define whether to print the entire content in one single page.
 If the singlePage form field is set to true, it automatically overrides the values from the paperHeight and nativePageRanges form fields.
@@ -91,14 +96,6 @@ For instance: "window.status === 'ready'".
 * `emulatedMediaType(Sensiolabs\GotenbergBundle\Enumeration\EmulatedMediaType $mediaType)`:
 Forces Chromium to emulate, either "screen" or "print". (default "print").
 
-* `cookies(array $cookies)`:
-Cookies to store in the Chromium cookie jar. (overrides any previous cookies).
-
-* `setCookie(string $key, array $cookie)`:
-
-* `addCookies(array $cookies)`:
-Add cookies to store in the Chromium cookie jar.
-
 * `extraHttpHeaders(array $headers)`:
 Sets extra HTTP headers that Chromium will send when loading the HTML
 document. (default None). (overrides any previous headers).
@@ -131,3 +128,8 @@ The metadata to write.
 
 * `fileName(string $fileName, string $headerDisposition)`:
 
+* `processor(Sensiolabs\GotenbergBundle\Processor\ProcessorInterface $processor)`:
+
+* `addCookies(array $cookies)`:
+Add cookies to store in the Chromium cookie jar.
+
diff --git a/docs/Screenshot/HtmlScreenshotBuilder.md → ...hot/builders_api/HtmlScreenshotBuilder.md b/docs/Screenshot/HtmlScreenshotBuilder.md → ...hot/builders_api/HtmlScreenshotBuilder.md
@@ -1,11 +1,16 @@
-HtmlScreenshotBuilder
-=====================
+# HtmlScreenshotBuilder
 
 * `content(string $template, array $context)`:
 
 * `contentFile(string $path)`:
 The HTML file to convert into Screenshot.
 
+* `cookies(array $cookies)`:
+
+* `setCookie(string $key, Symfony\Component\HttpFoundation\Cookie|array $cookie)`:
+
+* `forwardCookie(string $name)`:
+
 * `width(int $width)`:
 The device screen width in pixels. (Default 800).
 
@@ -37,17 +42,9 @@ Sets the JavaScript expression to wait before converting an HTML
 document to screenshot until it returns true. (default None).
 For instance: "window.status === 'ready'".
 
-* `emulatedMediaType(string $mediaType)`:
+* `emulatedMediaType(Sensiolabs\GotenbergBundle\Enumeration\EmulatedMediaType $mediaType)`:
 Forces Chromium to emulate, either "screen" or "print". (default "print").
 
-* `cookies(array $cookies)`:
-Cookies to store in the Chromium cookie jar. (overrides any previous cookies).
-
-* `setCookie(string $key, array $cookie)`:
-
-* `addCookies(array $cookies)`:
-Add cookies to store in the Chromium cookie jar.
-
 * `extraHttpHeaders(array $headers)`:
 Sets extra HTTP headers that Chromium will send when loading the HTML
 document. (default None). (overrides any previous headers).
@@ -74,3 +71,8 @@ Adds a file, like an image, font, stylesheet, and so on.
 
 * `fileName(string $fileName, string $headerDisposition)`:
 
+* `processor(Sensiolabs\GotenbergBundle\Processor\ProcessorInterface $processor)`:
+
+* `addCookies(array $cookies)`:
+Add cookies to store in the Chromium cookie jar.
+
diff --git a/docs/Screenshot/MarkdownScreenshotBuilder.md → ...builders_api/MarkdownScreenshotBuilder.md b/docs/Screenshot/MarkdownScreenshotBuilder.md → ...builders_api/MarkdownScreenshotBuilder.md
@@ -1,5 +1,4 @@
-MarkdownScreenshotBuilder
-=========================
+# MarkdownScreenshotBuilder
 
 * `wrapper(string $template, array $context)`:
 The HTML file that wraps the markdown content, rendered from a Twig template.
@@ -9,6 +8,12 @@ The HTML file that wraps the markdown content.
 
 * `files(string $paths)`:
 
+* `cookies(array $cookies)`:
+
+* `setCookie(string $key, Symfony\Component\HttpFoundation\Cookie|array $cookie)`:
+
+* `forwardCookie(string $name)`:
+
 * `width(int $width)`:
 The device screen width in pixels. (Default 800).
 
@@ -40,17 +45,9 @@ Sets the JavaScript expression to wait before converting an HTML
 document to screenshot until it returns true. (default None).
 For instance: "window.status === 'ready'".
 
-* `emulatedMediaType(string $mediaType)`:
+* `emulatedMediaType(Sensiolabs\GotenbergBundle\Enumeration\EmulatedMediaType $mediaType)`:
 Forces Chromium to emulate, either "screen" or "print". (default "print").
 
-* `cookies(array $cookies)`:
-Cookies to store in the Chromium cookie jar. (overrides any previous cookies).
-
-* `setCookie(string $key, array $cookie)`:
-
-* `addCookies(array $cookies)`:
-Add cookies to store in the Chromium cookie jar.
-
 * `extraHttpHeaders(array $headers)`:
 Sets extra HTTP headers that Chromium will send when loading the HTML
 document. (default None). (overrides any previous headers).
@@ -77,3 +74,8 @@ Adds a file, like an image, font, stylesheet, and so on.
 
 * `fileName(string $fileName, string $headerDisposition)`:
 
+* `processor(Sensiolabs\GotenbergBundle\Processor\ProcessorInterface $processor)`:
+
+* `addCookies(array $cookies)`:
+Add cookies to store in the Chromium cookie jar.
+