sphinxcontrib-screenshot 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

sphinxcontrib/screenshot.py

@@ -40,6 +40,9 @@ Meta = typing.TypedDict('Meta', {
     'parallel_write_safe': bool
 })
 
+ContextBuilder = typing.Optional[typing.Callable[[Browser, str, str],
+                                                 BrowserContext]]
+
 
 class ScreenshotDirective(SphinxDirective, Figure):
   """Sphinx Screenshot Dirctive.
@@ -79,6 +82,24 @@ class ScreenshotDirective(SphinxDirective, Figure):
   .. screenshot:: http://www.example.com
     :pdf:
   ```
+
+  You can take a screenshot of a local file using a root-relative path.
+
+  ```rst
+  .. screenshot:: /static/example.html
+  ```
+
+  Or you can use a document-relative path.
+
+  ```rst
+  .. screenshot:: ./example.html
+  ```
+
+  The `file://` protocol is also supported.
+
+  ```rst
+   .. screenshot:: file:///path/to/your/file.html
+   ```
   """
 
   required_arguments = 1  # URL
@@ -93,21 +114,25 @@ class ScreenshotDirective(SphinxDirective, Figure):
       'full-page': directives.flag,
       'context': str,
       'headers': directives.unchanged,
+      'locale': str,
+      'timezone': str,
+      'device-scale-factor': directives.positive_int,
   }
   pool = ThreadPoolExecutor()
 
   @staticmethod
-  def take_screenshot(
-      url: str, browser_name: str, viewport_width: int, viewport_height: int,
-      filepath: str, init_script: str, interactions: str, generate_pdf: bool,
-      color_scheme: ColorScheme, full_page: bool,
-      context_builder: typing.Optional[typing.Callable[[Browser, str, str],
-                                                       BrowserContext]],
-      headers: dict):
+  def take_screenshot(url: str, browser_name: str, viewport_width: int,
+                      viewport_height: int, filepath: str, init_script: str,
+                      interactions: str, generate_pdf: bool,
+                      color_scheme: ColorScheme, full_page: bool,
+                      context_builder: ContextBuilder, headers: dict,
+                      device_scale_factor: int, locale: typing.Optional[str],
+                      timezone: typing.Optional[str]):
     """Takes a screenshot with Playwright's Chromium browser.
 
     Args:
       url (str): The HTTP/HTTPS URL of the webpage to screenshot.
+      browser_name (str): Browser to use ('chromium', 'firefox' or 'webkit').
       viewport_width (int): The width of the screenshot in pixels.
       viewport_height (int): The height of the screenshot in pixels.
       filepath (str): The path to save the screenshot to.
@@ -118,10 +143,16 @@ class ScreenshotDirective(SphinxDirective, Figure):
         after the page was loaded.
       generate_pdf (bool): Generate a PDF file along with the screenshot.
       color_scheme (str): The preferred color scheme. Can be 'light' or 'dark'.
+      full_page (bool): Take a full page screenshot.
       context: A method to build the Playwright context.
+      headers (dict): Custom request header.
+      device_scale_factor (int): The device scale factor for the screenshot.
+        This can be thought of as DPR (device pixel ratio).
+      locale (str, optional): User locale for the request.
+      timezone (str, optional): User timezone for the request.
     """
     with sync_playwright() as playwright:
-      browser = getattr(playwright, browser_name).launch()
+      browser: Browser = getattr(playwright, browser_name).launch()
 
       if context_builder:
         try:
@@ -131,7 +162,11 @@ class ScreenshotDirective(SphinxDirective, Figure):
               'Timeout error occured at %s in executing py init script %s' %
               (url, context_builder.__name__))
       else:
-        context = browser.new_context(color_scheme=color_scheme)
+        context = browser.new_context(
+            color_scheme=color_scheme,
+            locale=locale,
+            timezone_id=timezone,
+            device_scale_factor=device_scale_factor)
 
       page = context.new_page()
       page.set_default_timeout(10000)
@@ -173,14 +208,33 @@ class ScreenshotDirective(SphinxDirective, Figure):
 
   def run(self) -> typing.Sequence[nodes.Node]:
     screenshot_init_script: str = self.env.config.screenshot_init_script or ''
+    docdir = os.path.dirname(self.env.doc2path(self.env.docname))
 
     # Ensure the screenshots directory exists
     ss_dirpath = os.path.join(self.env.app.outdir, '_static', 'screenshots')
     os.makedirs(ss_dirpath, exist_ok=True)
 
     # Parse parameters
-    raw_url = self.arguments[0]
-    url = self.evaluate_substitutions(raw_url)
+    raw_path = self.arguments[0]
+    url_or_filepath = self.evaluate_substitutions(raw_path)
+
+    # Check if the path is a local file path.
+    if urlparse(url_or_filepath).scheme == '':
+      # root-relative path
+      if url_or_filepath.startswith('/'):
+        url_or_filepath = os.path.join(self.env.srcdir,
+                                       url_or_filepath.lstrip('/'))
+      # document-relative path
+      else:
+        url_or_filepath = os.path.join(docdir, url_or_filepath)
+      url_or_filepath = "file://" + os.path.normpath(url_or_filepath)
+
+    if urlparse(url_or_filepath).scheme not in {'http', 'https', 'file'}:
+      raise RuntimeError(
+          f'Invalid URL: {url_or_filepath}. ' +
+          'Only HTTP/HTTPS/FILE URLs or root/document-relative file paths ' +
+          'are supported.')
+
     interactions = self.options.get('interactions', '')
     browser = self.options.get('browser',
                                self.env.config.screenshot_default_browser)
@@ -193,25 +247,28 @@ class ScreenshotDirective(SphinxDirective, Figure):
     pdf = 'pdf' in self.options
     full_page = ('full-page' in self.options or
                  self.env.config.screenshot_default_full_page)
+    locale = self.options.get('locale',
+                              self.env.config.screenshot_default_locale)
+    timezone = self.options.get('timezone',
+                                self.env.config.screenshot_default_timezone)
     context = self.options.get('context', '')
     headers = self.options.get('headers', '')
-
+    device_scale_factor = self.options.get(
+        'device-scale-factor',
+        self.env.config.screenshot_default_device_scale_factor)
     request_headers = {**self.env.config.screenshot_default_headers}
     if headers:
       for header in headers.strip().split("\n"):
         name, value = header.split(" ", 1)
         request_headers[name] = value
 
-    if urlparse(url).scheme not in {'http', 'https'}:
-      raise RuntimeError(
-          f'Invalid URL: {url}. Only HTTP/HTTPS URLs are supported.')
-
     # Generate filename based on hash of parameters
     hash_input = "_".join([
-        raw_url, browser,
+        raw_path, browser,
         str(viewport_height),
         str(viewport_width), color_scheme, context, interactions,
-        str(full_page)
+        str(full_page),
+        str(device_scale_factor)
     ])
     filename = hashlib.md5(hash_input.encode()).hexdigest() + '.png'
     filepath = os.path.join(ss_dirpath, filename)
@@ -224,15 +281,15 @@ class ScreenshotDirective(SphinxDirective, Figure):
 
     # Check if the file already exists. If not, take a screenshot
     if not os.path.exists(filepath):
-      fut = self.pool.submit(ScreenshotDirective.take_screenshot, url, browser,
-                             viewport_width, viewport_height, filepath,
-                             screenshot_init_script, interactions, pdf,
-                             color_scheme, full_page, context_builder,
-                             request_headers)
+      fut = self.pool.submit(ScreenshotDirective.take_screenshot,
+                             url_or_filepath, browser, viewport_width,
+                             viewport_height, filepath, screenshot_init_script,
+                             interactions, pdf, color_scheme, full_page,
+                             context_builder, request_headers,
+                             device_scale_factor, locale, timezone)
       fut.result()
 
     # Create image and figure nodes
-    docdir = os.path.dirname(self.env.doc2path(self.env.docname))
     rel_ss_dirpath = os.path.relpath(ss_dirpath, start=docdir)
     rel_filepath = os.path.join(rel_ss_dirpath, filename).replace(os.sep, '/')
 
@@ -311,6 +368,22 @@ def setup(app: Sphinx) -> Meta:
       'screenshot_default_headers', {},
       'env',
       description="The default headers to pass in requests")
+  app.add_config_value(
+      'screenshot_default_device_scale_factor',
+      1,
+      'env',
+      description="The default device scale factor " +
+      "a.k.a. DPR (device pixel ratio)")
+  app.add_config_value(
+      'screenshot_default_locale',
+      None,
+      'env',
+      description="The default locale in requests")
+  app.add_config_value(
+      'screenshot_default_timezone',
+      None,
+      'env',
+      description="The default timezone in requests")
   app.add_config_value(
       'screenshot_apps', {},
       'env',

{sphinxcontrib_screenshot-0.2.0.dist-info → sphinxcontrib_screenshot-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sphinxcontrib-screenshot
-Version: 0.2.0
+Version: 0.2.2
 Summary: A Sphinx extension to embed webpage screenshots.
 Author-email: Shuhei Iitsuka <tushuhei@gmail.com>
 License: Apache-2.0

sphinxcontrib_screenshot-0.2.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+sphinxcontrib/screenshot.py,sha256=Kb4oC4w-fv9qBYi251u5WeN_xvSLjwv0k3Ybs0R8xi4,14096
+sphinxcontrib_screenshot-0.2.2.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+sphinxcontrib_screenshot-0.2.2.dist-info/METADATA,sha256=S52Ju_7SvfeT5xDFia9m7ABh1f1egPSRMTVrey6ivok,2868
+sphinxcontrib_screenshot-0.2.2.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+sphinxcontrib_screenshot-0.2.2.dist-info/top_level.txt,sha256=VJrV3_vaiKQVgVpR0I1iecxoO0drzGu-M0j40PVP2QQ,14
+sphinxcontrib_screenshot-0.2.2.dist-info/RECORD,,

sphinxcontrib_screenshot-0.2.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-sphinxcontrib/screenshot.py,sha256=03cVsF1d9zuWMsVBwtZU_EQ_GMMsYyPa2a3vBmzC4f8,11342
-sphinxcontrib_screenshot-0.2.0.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-sphinxcontrib_screenshot-0.2.0.dist-info/METADATA,sha256=pwaSBQlzvflzW2BSv7ByJ8GvbwDrYF0xn8bftw3dPC0,2868
-sphinxcontrib_screenshot-0.2.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-sphinxcontrib_screenshot-0.2.0.dist-info/top_level.txt,sha256=VJrV3_vaiKQVgVpR0I1iecxoO0drzGu-M0j40PVP2QQ,14
-sphinxcontrib_screenshot-0.2.0.dist-info/RECORD,,