docs: improve documentation

Author: uptickmetachu

README.md

@@ -8,22 +8,39 @@ It is intended to be a DIY docraptor of sorts.
 
 Simply build the docker image, deploy it to AWS, then invoke the lambda with an event body JSON that performs the desired operation. For example: `{"document_content": "<h1>Hello, World!</h1>"}`
 
-## Ways of invoking splat
+This can be done via a function_url, apigateway or lambda invoke.
+
+## Invoking splat
+
+Event payload body.
+
+|Field | Type| Description|
+|---|---|---|
+| **javascript (princexml)**   |  boolean (False) | Enables [princeXML's javascript execution](https://www.princexml.com/doc/javascript/). This will not render react but can be used for formatting. |
+| **check_license**  |   boolean (False) | Send this field to receive a check on remaining license usage |
+| **document_content** | string | Embed the html content in the payload. There will be AWS payload size limitations.|
+| **document_url**| url | Fetch the html content from `document_url` to disk before rendering.|
+| **browser_url** | url | Browser the `browser_url` with `playwright` before rendering with `renderer`|
+| **browser_headers**| Mapping[str,str] | Add additional headers to playwright before visiting `browser_url`|
+| **renderer**| `princexml` or `playwright`| Renderer to render the html with |
+| **bucket_name**| string | Output the resulting pdf to `s3://{bucket_name}/{uuid}.pdf`. The lambda will require permission to upload to the bucket. The response will include `bucket`, `key`, `presigned_url`|
+| **presigned_url**| url | Output the resulting pdf to the presigned url. Generate the presigned url with `put_object`. See Output for more information.|
 
 ### Input
 
 Pass content in event: `{"document_content": "<h1>Hello, World!</h1>"}`
-Pass content via URL: `{"doucment_url": "<h1>Hello, World!</h1>"}`
+
+Pass content via URL: `{"document_url": "https://some_page/report.html"}`
+
+Pass content via Browser page: `{"browser_url": "https://some_react_page/", "renderer": "princexml", "browser_headers": {"Authorization": "Bearer SOME_BEARER_TOKEN"}}`
 
 ### Output
 
 Returns PDF base64 encoded by default.
-To save to an s3 bucket (lambda requires permission): `{"bucket_name": "<BUCKET>"}`
-To save to a presigned url: `{"presigned_url": "<URL>"}`
 
-### Options
+To save to an s3 bucket (lambda requires permission): `{"bucket_name": "<BUCKET>"}`
 
-To enable Javascript: `{"javascript": true}`
+To save to a presigned url: `{"presigned_url": "<URL>"}`
 
 ## PrinceXML License
 

lambda_function.py

@@ -32,10 +32,11 @@
 
 class Renderers(str, enum.Enum):
     playwright = "playwright"
-    prince = "prince"
+    princexml = "princexml"
 
 
 class Payload(pydantic.BaseModel):
+    # NOTE: When updating this model, also update the equivalent documentation
     # General Parameters
     javascript: bool = False
     check_license: bool = False
@@ -48,7 +49,7 @@ class Payload(pydantic.BaseModel):
     ## Browse the document in a browser before rendering
     browser_url: str | None = None
     browser_headers: dict = pydantic.Field(default_factory=dict)
-    renderer: Renderers = Renderers.prince
+    renderer: Renderers = Renderers.princexml
 
     # Output parameters
     bucket_name: str | None = None
@@ -126,7 +127,7 @@ def pdf_from_document_content(payload: Payload, output_filepath: str) -> None:
         assert payload.document_content
         temporary_html_file.write(payload.document_content)
         temporary_html_file.flush()
-        if payload.renderer == Renderers.prince:
+        if payload.renderer == Renderers.princexml:
             prince_handler(temporary_html_file.name, output_filepath, payload.javascript)
         else:
             playwright_page_to_pdf(f"file://{temporary_html_file.name}", payload.browser_headers, output_filepath)
@@ -144,7 +145,7 @@ def pdf_from_document_url(payload: Payload, output_filepath: str) -> None:
     with tempfile.NamedTemporaryFile(mode="w", suffix=".html") as temporary_html_file:
         temporary_html_file.write(response.content.decode("utf-8"))
         temporary_html_file.flush()
-        if payload.renderer == Renderers.prince:
+        if payload.renderer == Renderers.princexml:
             prince_handler(temporary_html_file.name, output_filepath, payload.javascript)
         else:
             playwright_page_to_pdf(f"file://{temporary_html_file.name}", payload.browser_headers, output_filepath)
@@ -155,9 +156,9 @@ def pdf_from_browser_url(payload: Payload, output_filepath: str) -> None:
     print("splat|pdf_from_browser_url")
     # First we need to visit the browser with playwright and save the html
     assert payload.browser_url
-    if payload.renderer == Renderers.prince:
+    if payload.renderer == Renderers.princexml:
         html = playwright_page_to_html_string(payload.browser_url, payload.browser_headers)
-        pdf_from_document_content(Payload(document_content=html, renderer=Renderers.prince), output_filepath)
+        pdf_from_document_content(Payload(document_content=html, renderer=Renderers.princexml), output_filepath)
     else:
         playwright_page_to_pdf(payload.browser_url, payload.browser_headers, output_filepath)
 

tests/test_lambda_e2e.py

@@ -53,7 +53,7 @@ def test_check_license_returns_a_license_payload() -> None:
     assert body["is_demo_license"] is False
 
 
-@pytest.mark.parametrize("renderer", ["prince", "playwright"])
+@pytest.mark.parametrize("renderer", ["princexml", "playwright"])
 class TestRenderers:
     def test_generating_pdf_from_document_url(self, renderer: str):
         s3_client = get_s3_client()