sphinxcontrib-screenshot 0.1.4__tar.gz → 0.2.1__tar.gz

{sphinxcontrib_screenshot-0.1.4/sphinxcontrib_screenshot.egg-info → sphinxcontrib_screenshot-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sphinxcontrib-screenshot
-Version: 0.1.4
+Version: 0.2.1
 Summary: A Sphinx extension to embed webpage screenshots.
 Author-email: Shuhei Iitsuka <tushuhei@gmail.com>
 License: Apache-2.0
@@ -53,8 +53,8 @@ A Sphinx extension to embed website screenshots.
 ```rst
 .. screenshot:: http://www.example.com
   :browser: chromium
-  :width: 1280
-  :height: 960
+  :viewport-width: 1280
+  :viewport-height: 960
   :color-scheme: dark
 ```
 

{sphinxcontrib_screenshot-0.1.4 → sphinxcontrib_screenshot-0.2.1}/README.md

@@ -5,8 +5,8 @@ A Sphinx extension to embed website screenshots.
 ```rst
 .. screenshot:: http://www.example.com
   :browser: chromium
-  :width: 1280
-  :height: 960
+  :viewport-width: 1280
+  :viewport-height: 960
   :color-scheme: dark
 ```
 

{sphinxcontrib_screenshot-0.1.4 → sphinxcontrib_screenshot-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sphinxcontrib-screenshot"
-version = "0.1.4"
+version = "0.2.1"
 description = "A Sphinx extension to embed webpage screenshots."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -69,6 +69,7 @@ include-package-data = true
 
 [tool.yapf]
 based_on_style = "yapf"
+column_limit = 79
 
 [tool.flake8]
 indent-size = 2

{sphinxcontrib_screenshot-0.1.4 → sphinxcontrib_screenshot-0.2.1}/sphinxcontrib/screenshot.py

@@ -24,7 +24,7 @@ from urllib.parse import urlparse
 
 from docutils import nodes
 from docutils.parsers.rst import directives
-from docutils.statemachine import ViewList
+from docutils.parsers.rst.directives.images import Figure
 from playwright._impl._helper import ColorScheme
 from playwright.sync_api import Browser, BrowserContext
 from playwright.sync_api import TimeoutError as PlaywrightTimeoutError
@@ -40,8 +40,11 @@ Meta = typing.TypedDict('Meta', {
     'parallel_write_safe': bool
 })
 
+ContextBuilder = typing.Optional[typing.Callable[[Browser, str, str],
+                                                 BrowserContext]]
 
-class ScreenshotDirective(SphinxDirective):
+
+class ScreenshotDirective(SphinxDirective, Figure):
   """Sphinx Screenshot Dirctive.
 
   This directive embeds a screenshot of a webpage.
@@ -54,20 +57,13 @@ class ScreenshotDirective(SphinxDirective):
   .. screenshot:: http://www.example.com
   ```
 
-  You can also specify the screen size for the screenshot with `width` and
-  `height` parameters in pixel.
+  You can also specify the screen size for the screenshot with
+  `viewport-width` and `viewport-height` parameters in pixel.
 
   ```rst
   .. screenshot:: http://www.example.com
-    :width: 1280
-    :height: 960
-  ```
-
-  You can include a caption for the screenshot's `figure` directive.
-
-  ```rst
-  .. screenshot:: http://www.example.com
-    :caption: This is a screenshot for www.example.com
+    :viewport-width: 1280
+    :viewport-height: 960
   ```
 
   You can describe the interaction that you want to have with the webpage
@@ -79,52 +75,65 @@ class ScreenshotDirective(SphinxDirective):
     document.querySelector('button').click();
   ```
 
-  Use `figclass` option if you want to specify a class name to the image.
+  It also generates a PDF file when `pdf` option is given, which might be
+  useful when you need scalable image assets.
 
   ```rst
   .. screenshot:: http://www.example.com
-    :figclass: foo
+    :pdf:
   ```
 
-  It also generates a PDF file when `pdf` option is given, which might be
-  useful when you need scalable image assets.
+  You can take a screenshot of a local file using a root-relative path.
 
   ```rst
-  .. screenshot:: http://www.example.com
-    :pdf:
+  .. 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
-  has_content = True
   option_spec = {
+      **Figure.option_spec,
       'browser': str,
-      'height': directives.positive_int,
-      'width': directives.positive_int,
-      'caption': directives.unchanged,
-      'figclass': directives.unchanged,
+      'viewport-height': directives.positive_int,
+      'viewport-width': directives.positive_int,
+      'interactions': str,
       'pdf': directives.flag,
       'color-scheme': str,
       'full-page': directives.flag,
       'context': str,
       'headers': directives.unchanged,
+      'locale': str,
+      'timezone': str,
   }
   pool = ThreadPoolExecutor()
 
   @staticmethod
-  def take_screenshot(
-      url: str, browser_name: str, width: int, 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,
+                      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.
-      width (int): The width of the screenshot in pixels.
-      height (int): The height of the screenshot in pixels.
+      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.
       init_script (str): JavaScript code to be evaluated after the document
         was created but before any of its scripts were run. See more details at
@@ -133,10 +142,14 @@ class ScreenshotDirective(SphinxDirective):
         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.
+      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:
@@ -146,11 +159,15 @@ class ScreenshotDirective(SphinxDirective):
               '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)
 
       page = context.new_page()
       page.set_default_timeout(10000)
-      page.set_viewport_size({'width': width, 'height': height})
+      page.set_viewport_size({
+          'width': viewport_width,
+          'height': viewport_height
+      })
 
       try:
         if init_script:
@@ -170,7 +187,10 @@ class ScreenshotDirective(SphinxDirective):
       if generate_pdf:
         page.emulate_media(media='screen')
         root, ext = os.path.splitext(filepath)
-        page.pdf(width=f'{width}px', height=f'{height}px', path=root + '.pdf')
+        page.pdf(
+            width=f'{viewport_width}px',
+            height=f'{viewport_height}px',
+            path=root + '.pdf')
       page.close()
       browser.close()
 
@@ -180,30 +200,52 @@ class ScreenshotDirective(SphinxDirective):
       text = text.replace(f"|{key}|", value.astext())
     return text
 
-  def run(self) -> typing.List[nodes.Node]:
+  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)
-    height = self.options.get('height',
-                              self.env.config.screenshot_default_height)
-    width = self.options.get('width', self.env.config.screenshot_default_width)
+    viewport_height = self.options.get(
+        'viewport-height', self.env.config.screenshot_default_viewport_height)
+    viewport_width = self.options.get(
+        'viewport-width', self.env.config.screenshot_default_viewport_width)
     color_scheme = self.options.get(
         'color-scheme', self.env.config.screenshot_default_color_scheme)
-    caption_text = self.options.get('caption', '')
-    figclass = self.options.get('figclass', '')
     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', '')
-    interactions = '\n'.join(self.content)
     headers = self.options.get('headers', '')
 
     request_headers = {**self.env.config.screenshot_default_headers}
@@ -212,15 +254,11 @@ class ScreenshotDirective(SphinxDirective):
         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,
-        str(height),
-        str(width), color_scheme, context, interactions,
+        raw_path, browser,
+        str(viewport_height),
+        str(viewport_width), color_scheme, context, interactions,
         str(full_page)
     ])
     filename = hashlib.md5(hash_input.encode()).hexdigest() + '.png'
@@ -234,30 +272,20 @@ class ScreenshotDirective(SphinxDirective):
 
     # 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,
-                             width, height, filepath, screenshot_init_script,
+      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)
+                             context_builder, request_headers, 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, '/')
-    image_node = nodes.image(uri=rel_filepath)
-    figure_node = nodes.figure('', image_node)
-
-    if figclass:
-      figure_node['classes'].append(figclass)
-
-    if caption_text:
-      parsed = nodes.Element()
-      self.state.nested_parse(
-          ViewList([caption_text], source=''), self.content_offset, parsed)
-      figure_node += nodes.caption(parsed[0].source or '', '',
-                                   *parsed[0].children)
 
-    return [figure_node]
+    self.arguments[0] = rel_filepath
+    return super().run()
 
 
 app_threads = {}
@@ -298,12 +326,12 @@ def setup(app: Sphinx) -> Meta:
   app.add_directive('screenshot', ScreenshotDirective)
   app.add_config_value('screenshot_init_script', '', 'env')
   app.add_config_value(
-      'screenshot_default_width',
+      'screenshot_default_viewport_width',
       1280,
       'env',
       description="The default width for screenshots")
   app.add_config_value(
-      'screenshot_default_height',
+      'screenshot_default_viewport_height',
       960,
       'env',
       description="The default height for screenshots")
@@ -331,6 +359,16 @@ def setup(app: Sphinx) -> Meta:
       'screenshot_default_headers', {},
       'env',
       description="The default headers to pass in requests")
+  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.1.4 → sphinxcontrib_screenshot-0.2.1/sphinxcontrib_screenshot.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sphinxcontrib-screenshot
-Version: 0.1.4
+Version: 0.2.1
 Summary: A Sphinx extension to embed webpage screenshots.
 Author-email: Shuhei Iitsuka <tushuhei@gmail.com>
 License: Apache-2.0
@@ -53,8 +53,8 @@ A Sphinx extension to embed website screenshots.
 ```rst
 .. screenshot:: http://www.example.com
   :browser: chromium
-  :width: 1280
-  :height: 960
+  :viewport-width: 1280
+  :viewport-height: 960
   :color-scheme: dark
 ```
 

{sphinxcontrib_screenshot-0.1.4 → sphinxcontrib_screenshot-0.2.1}/sphinxcontrib_screenshot.egg-info/SOURCES.txt

@@ -10,9 +10,10 @@ sphinxcontrib_screenshot.egg-info/top_level.txt
 tests/test_browsers.py
 tests/test_color_scheme.py
 tests/test_contexts.py
-tests/test_figclass.py
 tests/test_full_page.py
 tests/test_headers.py
+tests/test_locale.py
 tests/test_pdf.py
 tests/test_root.py
+tests/test_timezone.py
 tests/test_wsgi_apps.py

sphinxcontrib_screenshot-0.2.1/tests/test_locale.py

@@ -0,0 +1,48 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from io import StringIO
+
+import pytest
+from bs4 import BeautifulSoup
+from sphinx.testing.util import SphinxTestApp
+
+
+@pytest.mark.sphinx('html', testroot="locale")
+def test_locale(app: SphinxTestApp, status: StringIO, warning: StringIO,
+                image_regression) -> None:
+  app.build()
+  out_html = app.outdir / "index.html"
+
+  soup = BeautifulSoup(out_html.read_text(), "html.parser")
+  imgs = soup.find_all('img')
+
+  img_path = app.outdir / imgs[0]['src']
+  with open(img_path, "rb") as fd:
+    # Tolerance of 0.5%
+    image_regression.check(fd.read(), diff_threshold=0.5)
+
+
+@pytest.mark.sphinx('html', testroot="default-locale")
+def test_default_locale(app: SphinxTestApp, status: StringIO,
+                        warning: StringIO, image_regression) -> None:
+  app.build()
+  out_html = app.outdir / "index.html"
+
+  soup = BeautifulSoup(out_html.read_text(), "html.parser")
+  imgs = soup.find_all('img')
+
+  img_path = app.outdir / imgs[0]['src']
+  with open(img_path, "rb") as fd:
+    # Tolerance of 0.5%
+    image_regression.check(fd.read(), diff_threshold=0.5)

{sphinxcontrib_screenshot-0.1.4 → sphinxcontrib_screenshot-0.2.1}/tests/test_root.py

@@ -23,8 +23,7 @@ from sphinx.testing.util import SphinxTestApp
 @pytest.mark.sphinx('html', testroot='root')
 def test_default(app: SphinxTestApp) -> None:
   app.build()
-  out_html = app.outdir / "index.html"
-  soup = BeautifulSoup(out_html.read_text(), "html.parser")
+  soup = BeautifulSoup((app.outdir / "index.html").read_text(), "html.parser")
 
   # Every screenshot directive should become an image.
   imgs = soup.find_all('img')
@@ -36,21 +35,6 @@ def test_default(app: SphinxTestApp) -> None:
   assert width == 480
   assert height == 320
 
-  # The caption should be rendered.
-  figcaptions = [
-      figcaption.get_text().strip()
-      for figcaption in soup.select('figcaption span')
-  ]
-  assert figcaptions == [
-      'This is a test screenshot', 'This is another screenshot',
-      'Changing the background.'
-  ]
-
-  # The images should be the same if the difference is only the caption.
-  img_with_caption_a = imgs[0]
-  img_with_caption_b = imgs[1]
-  assert img_with_caption_a['src'] == img_with_caption_b['src']
-
   # The images should be different after the specified user interaction.
   imgsrc_before_interaction = app.outdir / imgs[1]['src']
   imgsrc_after_interaction = app.outdir / imgs[2]['src']
@@ -58,12 +42,26 @@ def test_default(app: SphinxTestApp) -> None:
   assert list(Image.open(imgsrc_before_interaction).getdata()) != list(
       Image.open(imgsrc_after_interaction).getdata())
 
+  soup = BeautifulSoup((app.outdir / "sections" / "index.html").read_text(),
+                       "html.parser")
+
+  # Every screenshot directive should become an image.
+  imgs = soup.find_all('img')
+  assert len(list(imgs)) == 2
+
+  # The images should be the same.
+  imgsrc_relative = app.outdir / "sections" / imgs[0]['src']
+  imgsrc_absolute = app.outdir / "sections" / imgs[1]['src']
+  assert imgsrc_relative != imgsrc_absolute
+  assert list(Image.open(imgsrc_relative).getdata()) == list(
+      Image.open(imgsrc_absolute).getdata())
+
 
 @pytest.mark.sphinx('html', testroot="default-size")
 def test_default_size(app: SphinxTestApp, status: StringIO, warning: StringIO,
                       image_regression) -> None:
-  """Test the 'screenshot_default_width' and
-  'screenshot_default_height' configuration parameters."""
+  """Test the 'screenshot_default_viewport_width' and
+  'screenshot_default_viewport_height' configuration parameters."""
   app.build()
   out_html = app.outdir / "index.html"
 

sphinxcontrib_screenshot-0.2.1/tests/test_timezone.py

@@ -0,0 +1,48 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from io import StringIO
+
+import pytest
+from bs4 import BeautifulSoup
+from sphinx.testing.util import SphinxTestApp
+
+
+@pytest.mark.sphinx('html', testroot="timezone")
+def test_timezone(app: SphinxTestApp, status: StringIO, warning: StringIO,
+                  image_regression) -> None:
+  app.build()
+  out_html = app.outdir / "index.html"
+
+  soup = BeautifulSoup(out_html.read_text(), "html.parser")
+  imgs = soup.find_all('img')
+
+  img_path = app.outdir / imgs[0]['src']
+  with open(img_path, "rb") as fd:
+    # Tolerance of 0.5%
+    image_regression.check(fd.read(), diff_threshold=0.5)
+
+
+@pytest.mark.sphinx('html', testroot="default-timezone")
+def test_default_timezone(app: SphinxTestApp, status: StringIO,
+                          warning: StringIO, image_regression) -> None:
+  app.build()
+  out_html = app.outdir / "index.html"
+
+  soup = BeautifulSoup(out_html.read_text(), "html.parser")
+  imgs = soup.find_all('img')
+
+  img_path = app.outdir / imgs[0]['src']
+  with open(img_path, "rb") as fd:
+    # Tolerance of 0.5%
+    image_regression.check(fd.read(), diff_threshold=0.5)

sphinxcontrib_screenshot-0.1.4/tests/test_figclass.py

@@ -1,28 +0,0 @@
-# Copyright 2023 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-import pytest
-from bs4 import BeautifulSoup
-from sphinx.testing.util import SphinxTestApp
-
-
-@pytest.mark.sphinx('html', testroot='figclass')
-def test_default(app: SphinxTestApp) -> None:
-  app.build()
-  out_html = app.outdir / "index.html"
-  soup = BeautifulSoup(out_html.read_text(), "html.parser")
-
-  # The figure node should have the class name specified.
-  figure = soup.select_one('figure.round')
-  assert figure is not None