From 1c9d9b714f3765a943fbe448a362fb05e2a7c802 Mon Sep 17 00:00:00 2001 From: maelanleborgne Date: Mon, 25 Dec 2023 20:32:36 +0100 Subject: [PATCH] Minor formatting and phrasing fixes (#4) --- docs/basic-usage.rst | 109 ++++++++++++++++++++++------------------- docs/configuration.rst | 10 ++-- docs/customization.rst | 23 ++++++--- docs/index.rst | 4 +- docs/installation.rst | 21 +++++++- 5 files changed, 100 insertions(+), 67 deletions(-) diff --git a/docs/basic-usage.rst b/docs/basic-usage.rst index bc28f84a..59738b89 100644 --- 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,8 +14,8 @@ 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 @@ -23,21 +23,21 @@ 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 - - - - - My PDF - - -

Hello world!

- - + + + + + My PDF + + +

Hello world!

+ + .. 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 - - - - - - My PDF - - - {% verbatim %} - {{ toHTML "file.md" }} - {% endverbatim %} - - - -.. 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 + + + + + + My PDF + + + {% verbatim %} + {{ toHTML "file.md" }} + {% endverbatim %} + + + +.. 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 index 4e910fcb..adf49eb2 100644 --- 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 index dc383059..df77cb8f 100644 --- 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. -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 index 8207b3a5..b9efd607 100644 --- 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 index f2693a24..4b61fecd 100644 --- 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/