Minor formatting and phrasing fixes (#4)

sensiolabs · Dec 25, 2023 · 1c9d9b7 · 1c9d9b7
1 parent 6bc2743
commit 1c9d9b7
Show file tree

Hide file tree

Showing 5 changed files with 100 additions and 67 deletions.
diff --git a/docs/basic-usage.rst b/docs/basic-usage.rst
@@ -5,7 +5,7 @@ Configuration
 -------------
 
 Next you'll need to configure ``base_uri`` in the application's configuration's
-file to call your pre-installed Gotenberg API.
+file to call your previously installed Gotenberg API.
 
 .. code-block:: yaml
 
@@ -14,30 +14,30 @@ file to call your pre-installed Gotenberg API.
     sensiolabs_gotenberg:
         base_uri: '%env(GOTENBERG_URL)%'
 
-Thanks to the autowiring, you can access the ``Gotenberg`` simply by type
-hinting it in your controller method or in your service: the service
+Thanks to the autowiring, you can access the ``Gotenberg`` service simply by
+type-hinting it in your controller method or in your service: the service
 ``sensiolabs_gotenberg`` will be automatically injected.
 
 Requirements
 ------------
 
 .. caution::
 
-    Every twig templates you pass throw Gotenberg need to have the following structure.
+    Every twig templates you pass to Gotenberg need to have the following structure.
     Even Header or Footer parts.
 
     .. code-block:: html
 
-    <!DOCTYPE html>
-    <html lang="en">
-      <head>
-        <meta charset="utf-8" />
-        <title>My PDF</title>
-      </head>
-      <body>
-        <h1>Hello world!</h1>
-      </body>
-    </html>
+        <!DOCTYPE html>
+        <html lang="en">
+          <head>
+            <meta charset="utf-8" />
+            <title>My PDF</title>
+          </head>
+          <body>
+            <h1>Hello world!</h1>
+          </body>
+        </html>
 
 .. tip::
 
@@ -46,11 +46,11 @@ Requirements
 Convert an HTML into PDF
 ------------------------
 
-After injecting ``Gotenberg`` you only need to call the method ``url``,
-who will return a``UrlPdfBuilder`` instance.
+After injecting ``Gotenberg`` you simply need to call the method ``url``,
+which will return a ``UrlPdfBuilder`` instance.
 
-``UrlPdfBuilder`` let you add the URL of the page you want to convert into PDF
-with the method ``content``.
+``UrlPdfBuilder`` lets you pass the URL of the page you want to convert into PDF
+to the method ``content``.
 
 .. code-block:: php
 
@@ -78,9 +78,11 @@ with the method ``content``.
 Convert a Twig template into PDF
 --------------------------------
 
-``TwigPdfBuilder`` has Twig environment service in his construct and can access
-to your configuration ``default_path`` about your templates. It will be more
-simple for you to add your templates and the datas you needs.
+``TwigPdfBuilder`` comes with the Twig Environment service and thus has access
+to your your templates ``default_path`` configuration. This makes it easy to
+pass the name of the templates to the builder. You can also pass
+variables to the templates through the second argument of the methods
+``content``, ``header`` and ``footer``.
 
 .. code-block:: php
 
@@ -114,34 +116,12 @@ Convert Markdown into PDF
 
 .. caution::
 
-    MarkdownPdfBuilder use Twig environment.
-    Because of the implementation way the markdown is added in the HTML template.
-    Gotenberg API wait ``e.g {{ toHTML "file.md" }}`` as synthax to add the file in it.
-    To don't ends up with an error you can use `verbatim`_ tag from twig.
-
-So your twig template who receive your markdown file need look like this.
-
-    .. code-block:: html
-
-        <!doctype html>
-        <html lang="en">
-                <head>
-                    <meta charset="utf-8">
-                    <title>My PDF</title>
-                </head>
-            <body>
-                {% verbatim %}
-                    {{ toHTML "file.md" }}
-                {% endverbatim %}
-            </body>
-        </html>
-
-.. warning::
+    MarkdownPdfBuilder uses Twig.
 
-    You need to have the same filename between the var in the HTML template and
-    the file added in ``markdownFile`` method.
+The ``MarkdownBuilder`` class has a ``content`` method that takes the name of
+the Twig template that will receive the Markdown, and ``markdownFile`` method
+that expects the local path of the Markdown file to convert.
 
-``markdownFile`` wait the directory where your file is located.
 
 .. code-block:: php
 
@@ -163,6 +143,32 @@ So your twig template who receive your markdown file need look like this.
         }
     }
 
+In the template, you can use the ``{{ toHTML "filename.md" }}`` special directive to reference the
+Markdown file. The twig template that receives your markdown file will look like this.
+
+    .. code-block:: html
+
+        <!doctype html>
+        <html lang="en">
+                <head>
+                    <meta charset="utf-8">
+                    <title>My PDF</title>
+                </head>
+            <body>
+                {% verbatim %}
+                    {{ toHTML "file.md" }}
+                {% endverbatim %}
+            </body>
+        </html>
+
+.. warning::
+    Gotenberg expects an HTML template containing the directive ``{{ toHTML "file.md" }}``.
+    To prevent any conflict, you may want to use the `verbatim`_ tag to
+    encapsulate the directive.
+
+    You need to have the same filename between the var in the HTML template and
+    the file added in ``markdownFile`` method.
+
 .. tip::
 
     For more informations go to Gotenberg documentations. (`Markdown file(s) into PDF`_)
@@ -171,7 +177,7 @@ So your twig template who receive your markdown file need look like this.
 Convert an Office document into PDF
 -----------------------------------
 
-``officeFile`` wait the directory where your file is located.
+To convert an Office file to pdf, just pass the file's path to the ``OfficePdfBuilder::officeFile`` method.
 
 .. code-block:: php
 
@@ -200,11 +206,12 @@ Convert an Office document into PDF
 Save the generated PDF
 ----------------------
 
-As you could see in the last examples, you can easily return the response from the
+As you can see in the examples above, you can easily return the response from the
 ``generate`` method to stream the response to the client.
 
-If you want to save the file locally, you can use the ``saveTo`` method, and the
-content of the PDF will be dump into the file in the directory you written.
+If you'd rather save the file locally, you can use the ``saveTo`` method.
+It takes the target's file path as argument, and the content of the PDF will be
+dumped into this file.
 
 .. code-block:: php
 

diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -3,11 +3,6 @@ Configuration
 
 The default configuration for the bundle looks like :
 
-.. caution::
-
-    If you don't configure anything, the defaults values on Gotenberg API
-    will be used.
-
 .. code-block:: yaml
 
     # app/config/sensiolabs_gotenberg.yml
@@ -36,6 +31,11 @@ The default configuration for the bundle looks like :
             pdf_format: null                    # None
             pdf_universal_access: null          # false
 
+.. caution::
+
+    If you don't configure anything, the defaults values on Gotenberg API
+    will be used.
+
 .. tip::
 
     For more information about the `defaults properties`_.

diff --git a/docs/customization.rst b/docs/customization.rst
@@ -1,14 +1,14 @@
 Customization
 =============
 
-Every Builder instance give you the possibility to configure the options,
-or override the options you already set in your ``sensiolabs_gotenberg.yml``
-before generating it, if your PDF need to have his own style.
+If your PDF needs to have its own style, every Builder instance give you
+the possibility to configure the options, or override the options you've
+already set in your ``sensiolabs_gotenberg.yml``.
 
 .. note::
 
-    All of the next example will be realised with a ``TwigBuilder``, but
-    every customization methods belows can be done to every builders.
+    All of the following examples are made using a ``TwigBuilder``, but
+    each of the customization methods below apply to all builders.
 
 .. tip::
 
@@ -17,7 +17,8 @@ before generating it, if your PDF need to have his own style.
 Additional Assets
 -----------------
 
-You may also send additional files, like images, fonts, stylesheets, and so on.
+You can reference any file (like images, fonts, stylesheets, and so on...)
+from within a template.
 
 .. warning::
     The only requirement is that their paths in the template file are on the root level.
@@ -39,7 +40,8 @@ You may also send additional files, like images, fonts, stylesheets, and so on.
         </body>
     </html>
 
-And you can add it with the ``assets`` method.
+When building the PDF, you just have to use the ``assets`` method to add any
+asset referenced in the template to the request.
 
 .. code-block:: php
 
@@ -61,7 +63,7 @@ And you can add it with the ``assets`` method.
 Paper size
 ----------
 
-You can override the default paper size with (width and height, in inches):
+You can override the default paper size with width and height (in inches):
 
 .. code-block:: php
 
@@ -127,10 +129,15 @@ Hide the default white background and allow generating PDFs with transparency.
     The rules regarding the printBackground and omitBackground form fields are the following:
 
         If printBackground is set to false, no background is printed.
+
         If printBackground is set to true:
+
             If the HTML document has a background, that background is used.
+
             If not:
+
                 If omitBackground is set to true, the default background is transparent.
+
                 If not, the default white background is used.
 
 Landscape orientation

diff --git a/docs/index.rst b/docs/index.rst
@@ -3,7 +3,7 @@ GotenbergBundle
 
 .. caution::
 
-    To use this bundle, you must need to have installed `Gotenberg 7.x`_ first
+    To use this bundle, you first need to install and configure `Gotenberg 7.x`_.
 
 Overview
 --------
@@ -28,4 +28,4 @@ Chapters
     customization
 
 .. _Gotenberg 7.x: https://gotenberg.dev/
-.. _`GotenbergBundle`: https://github.com/sensiolabs
+.. _`GotenbergBundle`: https://github.com/sensiolabs/GotenbergBundle
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -3,6 +3,25 @@ Installation
 
 .. caution::
 
-    To use this bundle, you must need to have installed `Gotenberg 7.x`_ first
+    To use this bundle, you first need to install and configure `Gotenberg 7.x`_.
+
+Install the bundle using composer :
+
+.. code-block:: bash
+
+    composer require sensiolabs/gotenberg-bundle
+
+If not using Symfony Flex, enable the bundle by adding it to the list of
+registered bundles in the ``config/bundles.php`` file of your project:
+
+.. code-block:: php
+
+    // config/bundles.php
+
+    return [
+        // ...
+        SensioLabs\GotenbergBundle\SensioLabsGotenbergBundle::class => ['all' => true],
+    ];
+
 
 .. _Gotenberg 7.x: https://gotenberg.dev/