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

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

@@ -1,103 +1,64 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: sphinxcontrib-screenshot
-Version: 0.1.3
-Summary: A Shpinx extension to embed webpage screenshots.
-Home-page: https://github.com/tushuhei/sphinxcontrib-screenshot/
-Author: Shuhei Iitsuka
-Author-email: tushuhei@gmail.com
+Version: 0.1.4
+Summary: A Sphinx extension to embed webpage screenshots.
+Author-email: Shuhei Iitsuka <tushuhei@gmail.com>
 License: Apache-2.0
+Project-URL: repository, https://github.com/tushuhei/sphinxcontrib-screenshot/
 Classifier: Development Status :: 3 - Alpha
 Classifier: Operating System :: OS Independent
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: playwright
 Requires-Dist: sphinx
+Requires-Dist: portpicker
 Provides-Extra: dev
 Requires-Dist: beautifulsoup4; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-pyproject; extra == "dev"
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: Pillow; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-regressions[image]; extra == "dev"
 Requires-Dist: sphinx[test]; extra == "dev"
 Requires-Dist: toml; extra == "dev"
+Requires-Dist: tox; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-beautifulsoup4; extra == "dev"
 Requires-Dist: types-docutils; extra == "dev"
+Requires-Dist: types-portpicker; extra == "dev"
 Requires-Dist: types-Pillow; extra == "dev"
 Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: user-agents; extra == "dev"
 Requires-Dist: yapf; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: shibuya; extra == "doc"
+Requires-Dist: sphinx; extra == "doc"
 
 # sphinxcontrib-screenshot
 
 A Sphinx extension to embed website screenshots.
 
-![Example screenshot](https://raw.githubusercontent.com/tushuhei/sphinxcontrib-screenshot/main/example.png)
-
-## Install
-
-```bash
-pip install sphinxcontrib-screenshot
-playwright install
-```
-
-## Usage
-
-Add `sphinxcontrib.screenshot` to your `conf.py`.
-
-```py
-extensions = ["sphinxcontrib.screenshot"]
-```
-
-Then use the `screenshot` directive in your Sphinx source file.
-
-```rst
-.. screenshot:: http://www.example.com
-```
-
-You can also specify the screen size for the screenshot with `width` and `height` parameters.
-
 ```rst
 .. screenshot:: http://www.example.com
+  :browser: chromium
   :width: 1280
   :height: 960
+  :color-scheme: dark
 ```
 
-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
-```
-
-You can describe the interaction that you want to have with the webpage before taking a screenshot in JavaScript.
-
-```rst
-.. screenshot:: http://www.example.com
-
-  document.querySelector('button').click();
-```
-
-## Pro tips
-`sphinxcontrib-screenshot` supports URLs with the HTTP and HTTPS protocols.
-To take screenshots of local files and build the document while running a local server for them, you can use the NPM library [concurrently](https://www.npmjs.com/package/concurrently) in the following way:
-
-### Build the document
-```bash
-  npx --yes concurrently -k --success=first "make html" "python3 -m http.server 3000 --directory=examples"
-```
-
-### Watch and build the document
-```bash
-  npx --yes concurrently -k "make livehtml" "python3 -m http.server 3000 --directory=examples"
-```
-
+Read more in the [documentation](https://sphinxcontrib-screenshot.readthedocs.io).
 
 ## Notes
 

sphinxcontrib_screenshot-0.1.4/README.md

@@ -0,0 +1,33 @@
+# sphinxcontrib-screenshot
+
+A Sphinx extension to embed website screenshots.
+
+```rst
+.. screenshot:: http://www.example.com
+  :browser: chromium
+  :width: 1280
+  :height: 960
+  :color-scheme: dark
+```
+
+Read more in the [documentation](https://sphinxcontrib-screenshot.readthedocs.io).
+
+## Notes
+
+This extension uses [Playwright](https://playwright.dev) to capture a screenshot of the specified website only.
+No data is sent to any other external server; the request is limited to the specified website.
+Be cautious: avoid including sensitive information (such as authentication data) in the directive content.
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.
+
+## License
+
+Apache 2.0; see [`LICENSE`](LICENSE) for details.
+
+## Disclaimer
+
+This project is not an official Google project. It is not supported by
+Google and Google specifically disclaims all warranties as to its quality,
+merchantability, or fitness for a particular purpose.

sphinxcontrib_screenshot-0.1.4/pyproject.toml

@@ -0,0 +1,109 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sphinxcontrib-screenshot"
+version = "0.1.4"
+description = "A Sphinx extension to embed webpage screenshots."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Shuhei Iitsuka", email = "tushuhei@gmail.com" }
+]
+urls = { repository = "https://github.com/tushuhei/sphinxcontrib-screenshot/" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "playwright",
+    "sphinx",
+    "portpicker",
+]
+
+[project.optional-dependencies]
+dev = [
+    "beautifulsoup4",
+    "build",
+    "flake8",
+    "flake8-pyproject",
+    "isort",
+    "mypy",
+    "Pillow",
+    "pre-commit",
+    "pytest",
+    "pytest-regressions[image]",
+    "sphinx[test]",
+    "toml",
+    "tox",
+    "twine",
+    "types-beautifulsoup4",
+    "types-docutils",
+    "types-portpicker",
+    "types-Pillow",
+    "types-setuptools",
+    "user-agents",
+    "yapf",
+]
+
+doc = [
+    "myst-parser",
+    "shibuya",
+    "sphinx",
+]
+
+[tool.setuptools]
+packages = ["sphinxcontrib"]
+include-package-data = true
+
+[tool.setuptools.package-data]
+"sphinxcontrib" = ["*"]
+
+[tool.yapf]
+based_on_style = "yapf"
+
+[tool.flake8]
+indent-size = 2
+
+[tool.mypy]
+python_version = 3.9
+pretty = true
+packages = ["sphinxcontrib"]
+
+[tool.tox]
+requires = ["tox>=4.19"]
+env_list = [
+    "py39",
+    "py310",
+    "py311",
+    "py312",
+    "py313",
+    "style",
+]
+
+[tool.tox.env_run_base]
+deps = ["-e .[dev]"]
+commands = [
+    ["pytest", "--showlocals", "--full-trace", "{posargs}"],
+]
+
+[tool.tox.env.style]
+skip_install = true
+commands = [
+    ["pre-commit", "run", "--all-files", "--show-diff-on-failure"],
+]
+
+[tool.tox.env.doc]
+skip_install = true
+deps = ["-e .[doc]"]
+commands = [
+    ["sphinx-build", "--builder", "html", "doc", "build/sphinx/html"],
+]

sphinxcontrib_screenshot-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

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

@@ -13,17 +13,25 @@
 # limitations under the License.
 
 import hashlib
+import importlib
+import importlib.metadata
 import os
+import threading
 import typing
+import wsgiref.simple_server
 from concurrent.futures import ThreadPoolExecutor
 from urllib.parse import urlparse
 
 from docutils import nodes
 from docutils.parsers.rst import directives
 from docutils.statemachine import ViewList
+from playwright._impl._helper import ColorScheme
+from playwright.sync_api import Browser, BrowserContext
 from playwright.sync_api import TimeoutError as PlaywrightTimeoutError
 from playwright.sync_api import sync_playwright
+from portpicker import pick_unused_port
 from sphinx.application import Sphinx
+from sphinx.config import Config
 from sphinx.util.docutils import SphinxDirective
 
 Meta = typing.TypedDict('Meta', {
@@ -32,8 +40,6 @@ Meta = typing.TypedDict('Meta', {
     'parallel_write_safe': bool
 })
 
-__version__ = '0.1.3'
-
 
 class ScreenshotDirective(SphinxDirective):
   """Sphinx Screenshot Dirctive.
@@ -92,17 +98,27 @@ class ScreenshotDirective(SphinxDirective):
   required_arguments = 1  # URL
   has_content = True
   option_spec = {
+      'browser': str,
       'height': directives.positive_int,
       'width': directives.positive_int,
       'caption': directives.unchanged,
       'figclass': directives.unchanged,
       'pdf': directives.flag,
+      'color-scheme': str,
+      'full-page': directives.flag,
+      'context': str,
+      'headers': directives.unchanged,
   }
   pool = ThreadPoolExecutor()
 
   @staticmethod
-  def take_screenshot(url: str, width: int, height: int, filepath: str,
-                      init_script: str, interactions: str, generate_pdf: bool):
+  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):
     """Takes a screenshot with Playwright's Chromium browser.
 
     Args:
@@ -116,15 +132,30 @@ class ScreenshotDirective(SphinxDirective):
       interactions (str): JavaScript code to run before taking the screenshot
         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'.
+      context: A method to build the Playwright context.
     """
     with sync_playwright() as playwright:
-      browser = playwright.chromium.launch()
-      page = browser.new_page()
+      browser = getattr(playwright, browser_name).launch()
+
+      if context_builder:
+        try:
+          context = context_builder(browser, url, color_scheme)
+        except PlaywrightTimeoutError:
+          raise RuntimeError(
+              'Timeout error occured at %s in executing py init script %s' %
+              (url, context_builder.__name__))
+      else:
+        context = browser.new_context(color_scheme=color_scheme)
+
+      page = context.new_page()
       page.set_default_timeout(10000)
       page.set_viewport_size({'width': width, 'height': height})
+
       try:
         if init_script:
           page.add_init_script(init_script)
+        page.set_extra_http_headers(headers)
         page.goto(url)
         page.wait_for_load_state('networkidle')
 
@@ -135,7 +166,7 @@ class ScreenshotDirective(SphinxDirective):
       except PlaywrightTimeoutError:
         raise RuntimeError('Timeout error occured at %s in executing\n%s' %
                            (url, interactions))
-      page.screenshot(path=filepath)
+      page.screenshot(path=filepath, full_page=full_page)
       if generate_pdf:
         page.emulate_media(media='screen')
         root, ext = os.path.splitext(filepath)
@@ -143,6 +174,12 @@ class ScreenshotDirective(SphinxDirective):
       page.close()
       browser.close()
 
+  def evaluate_substitutions(self, text: str) -> str:
+    substitutions = self.state.document.substitution_defs
+    for key, value in substitutions.items():
+      text = text.replace(f"|{key}|", value.astext())
+    return text
+
   def run(self) -> typing.List[nodes.Node]:
     screenshot_init_script: str = self.env.config.screenshot_init_script or ''
 
@@ -151,28 +188,56 @@ class ScreenshotDirective(SphinxDirective):
     os.makedirs(ss_dirpath, exist_ok=True)
 
     # Parse parameters
-    url = self.arguments[0]
-    height = self.options.get('height', 960)
-    width = self.options.get('width', 1280)
+    raw_url = self.arguments[0]
+    url = self.evaluate_substitutions(raw_url)
+    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)
+    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)
+    context = self.options.get('context', '')
     interactions = '\n'.join(self.content)
+    headers = self.options.get('headers', '')
+
+    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 = f'{url}_{height}_{width}_{interactions}'
+    hash_input = "_".join([
+        raw_url, browser,
+        str(height),
+        str(width), color_scheme, context, interactions,
+        str(full_page)
+    ])
     filename = hashlib.md5(hash_input.encode()).hexdigest() + '.png'
     filepath = os.path.join(ss_dirpath, filename)
 
+    if context:
+      context_builder_path = self.config.screenshot_contexts[context]
+      context_builder = resolve_python_method(context_builder_path)
+    else:
+      context_builder = None
+
     # 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, width,
-                             height, filepath, screenshot_init_script,
-                             interactions, pdf)
+      fut = self.pool.submit(ScreenshotDirective.take_screenshot, url, browser,
+                             width, height, filepath, screenshot_init_script,
+                             interactions, pdf, color_scheme, full_page,
+                             context_builder, request_headers)
       fut.result()
 
     # Create image and figure nodes
@@ -195,11 +260,86 @@ class ScreenshotDirective(SphinxDirective):
     return [figure_node]
 
 
+app_threads = {}
+
+
+def resolve_python_method(import_path: str):
+  module_path, method_name = import_path.split(":")
+  module = importlib.import_module(module_path)
+  method = getattr(module, method_name)
+  return method
+
+
+def setup_apps(app: Sphinx, config: Config):
+  """Start the WSGI application threads.
+
+    A new replacement is created for each WSGI app."""
+  for wsgi_app_name, wsgi_app_path in config.screenshot_apps.items():
+    port = pick_unused_port()
+    config.rst_prolog = (
+        config.rst_prolog or
+        "") + f"\n.. |{wsgi_app_name}| replace:: http://localhost:{port}\n"
+    app_builder = resolve_python_method(wsgi_app_path)
+    wsgi_app = app_builder(app)
+    httpd = wsgiref.simple_server.make_server("localhost", port, wsgi_app)
+    thread = threading.Thread(target=httpd.serve_forever)
+    thread.start()
+    app_threads[wsgi_app_name] = (httpd, thread)
+
+
+def teardown_apps(app: Sphinx, exception: typing.Optional[Exception]):
+  """Shut down the WSGI application threads."""
+  for httpd, thread in app_threads.values():
+    httpd.shutdown()
+    thread.join()
+
+
 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',
+      1280,
+      'env',
+      description="The default width for screenshots")
+  app.add_config_value(
+      'screenshot_default_height',
+      960,
+      'env',
+      description="The default height for screenshots")
+  app.add_config_value(
+      'screenshot_default_browser',
+      'chromium',
+      'env',
+      description="The default browser for screenshots")
+  app.add_config_value(
+      'screenshot_default_full_page',
+      False,
+      'env',
+      description="Whether to take full page screenshots")
+  app.add_config_value(
+      'screenshot_default_color_scheme',
+      'null',
+      'env',
+      description="The default color scheme for screenshots")
+  app.add_config_value(
+      'screenshot_contexts', {},
+      'env',
+      types=[dict[str, str]],
+      description="A dict of paths to Playwright context build methods")
+  app.add_config_value(
+      'screenshot_default_headers', {},
+      'env',
+      description="The default headers to pass in requests")
+  app.add_config_value(
+      'screenshot_apps', {},
+      'env',
+      types=[dict[str, str]],
+      description="A dict of WSGI apps")
+  app.connect('config-inited', setup_apps)
+  app.connect('build-finished', teardown_apps)
   return {
-      'version': __version__,
+      'version': importlib.metadata.version('sphinxcontrib-screenshot'),
       'parallel_read_safe': True,
       'parallel_write_safe': True,
   }

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

@@ -1,103 +1,64 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: sphinxcontrib-screenshot
-Version: 0.1.3
-Summary: A Shpinx extension to embed webpage screenshots.
-Home-page: https://github.com/tushuhei/sphinxcontrib-screenshot/
-Author: Shuhei Iitsuka
-Author-email: tushuhei@gmail.com
+Version: 0.1.4
+Summary: A Sphinx extension to embed webpage screenshots.
+Author-email: Shuhei Iitsuka <tushuhei@gmail.com>
 License: Apache-2.0
+Project-URL: repository, https://github.com/tushuhei/sphinxcontrib-screenshot/
 Classifier: Development Status :: 3 - Alpha
 Classifier: Operating System :: OS Independent
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: playwright
 Requires-Dist: sphinx
+Requires-Dist: portpicker
 Provides-Extra: dev
 Requires-Dist: beautifulsoup4; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-pyproject; extra == "dev"
 Requires-Dist: isort; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: Pillow; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-regressions[image]; extra == "dev"
 Requires-Dist: sphinx[test]; extra == "dev"
 Requires-Dist: toml; extra == "dev"
+Requires-Dist: tox; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-beautifulsoup4; extra == "dev"
 Requires-Dist: types-docutils; extra == "dev"
+Requires-Dist: types-portpicker; extra == "dev"
 Requires-Dist: types-Pillow; extra == "dev"
 Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: user-agents; extra == "dev"
 Requires-Dist: yapf; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: shibuya; extra == "doc"
+Requires-Dist: sphinx; extra == "doc"
 
 # sphinxcontrib-screenshot
 
 A Sphinx extension to embed website screenshots.
 
-![Example screenshot](https://raw.githubusercontent.com/tushuhei/sphinxcontrib-screenshot/main/example.png)
-
-## Install
-
-```bash
-pip install sphinxcontrib-screenshot
-playwright install
-```
-
-## Usage
-
-Add `sphinxcontrib.screenshot` to your `conf.py`.
-
-```py
-extensions = ["sphinxcontrib.screenshot"]
-```
-
-Then use the `screenshot` directive in your Sphinx source file.
-
-```rst
-.. screenshot:: http://www.example.com
-```
-
-You can also specify the screen size for the screenshot with `width` and `height` parameters.
-
 ```rst
 .. screenshot:: http://www.example.com
+  :browser: chromium
   :width: 1280
   :height: 960
+  :color-scheme: dark
 ```
 
-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
-```
-
-You can describe the interaction that you want to have with the webpage before taking a screenshot in JavaScript.
-
-```rst
-.. screenshot:: http://www.example.com
-
-  document.querySelector('button').click();
-```
-
-## Pro tips
-`sphinxcontrib-screenshot` supports URLs with the HTTP and HTTPS protocols.
-To take screenshots of local files and build the document while running a local server for them, you can use the NPM library [concurrently](https://www.npmjs.com/package/concurrently) in the following way:
-
-### Build the document
-```bash
-  npx --yes concurrently -k --success=first "make html" "python3 -m http.server 3000 --directory=examples"
-```
-
-### Watch and build the document
-```bash
-  npx --yes concurrently -k "make livehtml" "python3 -m http.server 3000 --directory=examples"
-```
-
+Read more in the [documentation](https://sphinxcontrib-screenshot.readthedocs.io).
 
 ## Notes
 

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

@@ -1,11 +1,18 @@
 LICENSE
 README.md
-setup.cfg
-setup.py
+pyproject.toml
 sphinxcontrib/screenshot.py
 sphinxcontrib_screenshot.egg-info/PKG-INFO
 sphinxcontrib_screenshot.egg-info/SOURCES.txt
 sphinxcontrib_screenshot.egg-info/dependency_links.txt
 sphinxcontrib_screenshot.egg-info/requires.txt
 sphinxcontrib_screenshot.egg-info/top_level.txt
-tests/test_it.py
+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_pdf.py
+tests/test_root.py
+tests/test_wsgi_apps.py

{sphinxcontrib_screenshot-0.1.3 → sphinxcontrib_screenshot-0.1.4}/sphinxcontrib_screenshot.egg-info/requires.txt

@@ -1,19 +1,31 @@
 playwright
 sphinx
+portpicker
 
 [dev]
 beautifulsoup4
 build
 flake8
+flake8-pyproject
 isort
 mypy
 Pillow
+pre-commit
 pytest
+pytest-regressions[image]
 sphinx[test]
 toml
+tox
 twine
 types-beautifulsoup4
 types-docutils
+types-portpicker
 types-Pillow
 types-setuptools
+user-agents
 yapf
+
+[doc]
+myst-parser
+shibuya
+sphinx

sphinxcontrib_screenshot-0.1.4/tests/test_browsers.py

@@ -0,0 +1,49 @@
+# Copyright 2024 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
+
+browsers = ["chromium", "firefox"]
+
+
+@pytest.mark.parametrize("browser", browsers)
+@pytest.mark.sphinx('html', testroot="browsers")
+def test_browser_option(browser, app: SphinxTestApp, status: StringIO,
+                        warning: StringIO, image_regression) -> None:
+  app.build()
+  out_html = app.outdir / f"{browser}.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:
+    image_regression.check(fd.read())
+
+
+@pytest.mark.sphinx('html', testroot="default-browser")
+def test_default_browser(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:
+    image_regression.check(fd.read())

sphinxcontrib_screenshot-0.1.4/tests/test_color_scheme.py

@@ -0,0 +1,48 @@
+# Copyright 2024 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="color-schemes")
+def test_color_scheme_option(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:
+    image_regression.check(fd.read())
+
+
+@pytest.mark.sphinx('html', testroot="default-color-scheme")
+def test_default_color_scheme_config_parameter(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:
+    image_regression.check(fd.read())

sphinxcontrib_screenshot-0.1.4/tests/test_contexts.py

@@ -0,0 +1,32 @@
+# Copyright 2024 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="contexts")
+def test_default(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:
+    image_regression.check(fd.read())

sphinxcontrib_screenshot-0.1.3/setup.py → sphinxcontrib_screenshot-0.1.4/tests/test_figclass.py

@@ -12,6 +12,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from setuptools import setup
+import pytest
+from bs4 import BeautifulSoup
+from sphinx.testing.util import SphinxTestApp
 
-setup()
+
+@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

sphinxcontrib_screenshot-0.1.4/tests/test_full_page.py

@@ -0,0 +1,46 @@
+# Copyright 2024 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="full-page")
+def test_full_page_option(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:
+    image_regression.check(fd.read())
+
+
+@pytest.mark.sphinx('html', testroot="default-full-page")
+def test_default_full_page(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:
+    image_regression.check(fd.read())

sphinxcontrib_screenshot-0.1.4/tests/test_headers.py

@@ -0,0 +1,33 @@
+# Copyright 2024 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="headers")
+def test_headers(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_pdf.py

@@ -0,0 +1,34 @@
+# 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 os
+
+import pytest
+from bs4 import BeautifulSoup
+from sphinx.testing.util import SphinxTestApp
+
+
+@pytest.mark.sphinx('html', testroot='pdf')
+def test_default(app: SphinxTestApp) -> None:
+  app.build()
+  out_html = app.outdir / "index.html"
+  soup = BeautifulSoup(out_html.read_text(), "html.parser")
+  img = soup.select_one('img')
+  assert img
+
+  imgsrc = str(img['src'])
+  root, ext = os.path.splitext(os.path.basename(imgsrc))
+  pdf_filepath = app.outdir / '_static' / 'screenshots' / f'{root}.pdf'
+  # Should generate a screenshot PDF.
+  assert os.path.exists(pdf_filepath)

sphinxcontrib_screenshot-0.1.3/tests/test_it.py → sphinxcontrib_screenshot-0.1.4/tests/test_root.py

@@ -12,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import os
 from io import StringIO
 
 import pytest
@@ -21,16 +20,15 @@ from PIL import Image
 from sphinx.testing.util import SphinxTestApp
 
 
-@pytest.mark.sphinx('html')
-def test_default(app: SphinxTestApp, status: StringIO,
-                 warning: StringIO) -> None:
+@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")
 
   # Every screenshot directive should become an image.
   imgs = soup.find_all('img')
-  assert len(list(imgs)) == 5
+  assert len(list(imgs)) == 3
 
   # The image size should be set as specified.
   img_obj = Image.open(app.outdir / imgs[0]['src'])
@@ -39,32 +37,40 @@ def test_default(app: SphinxTestApp, status: StringIO,
   assert height == 320
 
   # The caption should be rendered.
-  figcaption = soup.select_one('figcaption span')
-  assert figcaption and (figcaption.get_text().strip()
-                         == 'This is a test screenshot')
-
-  # The images should be different after the specified user interaction.
-  img_before_interaction = Image.open(app.outdir / imgs[0]['src'])
-  img_after_interaction = Image.open(app.outdir / imgs[2]['src'])
-  assert list(img_before_interaction.getdata()) != list(
-      img_after_interaction.getdata())
+  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 figure node should have the class name specified.
-  assert 'round' in soup.find_all('figure')[3]['class']
+  # 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']
+  assert imgsrc_before_interaction != imgsrc_after_interaction
+  assert list(Image.open(imgsrc_before_interaction).getdata()) != list(
+      Image.open(imgsrc_after_interaction).getdata())
+
 
-  # Should generate a PDF file if specified.
-  img_with_pdf = imgs[4]['src']
-  root, ext = os.path.splitext(os.path.basename(img_with_pdf))
-  pdf_filepath = app.outdir / '_static' / 'screenshots' / f'{root}.pdf'
-  assert os.path.exists(pdf_filepath)
+@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."""
+  app.build()
+  out_html = app.outdir / "index.html"
 
-  # Should not generate a PDF file if not specified.
-  img_without_pdf = imgs[2]['src']
-  root, ext = os.path.splitext(os.path.basename(img_without_pdf))
-  pdf_filepath = app.outdir / '_static' / 'screenshots' / f'{root}.pdf'
-  assert not os.path.exists(pdf_filepath)
+  soup = BeautifulSoup(out_html.read_text(), "html.parser")
+  imgs = soup.find_all('img')
+
+  img_obj = Image.open(app.outdir / imgs[0]['src'])
+  width, height = img_obj.size
+  assert width == 1920
+  assert height == 1200

sphinxcontrib_screenshot-0.1.4/tests/test_wsgi_apps.py

@@ -0,0 +1,32 @@
+# Copyright 2024 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="wsgi-apps")
+def test_default(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:
+    image_regression.check(fd.read())

sphinxcontrib_screenshot-0.1.3/README.md

@@ -1,84 +0,0 @@
-# sphinxcontrib-screenshot
-
-A Sphinx extension to embed website screenshots.
-
-![Example screenshot](https://raw.githubusercontent.com/tushuhei/sphinxcontrib-screenshot/main/example.png)
-
-## Install
-
-```bash
-pip install sphinxcontrib-screenshot
-playwright install
-```
-
-## Usage
-
-Add `sphinxcontrib.screenshot` to your `conf.py`.
-
-```py
-extensions = ["sphinxcontrib.screenshot"]
-```
-
-Then use the `screenshot` directive in your Sphinx source file.
-
-```rst
-.. screenshot:: http://www.example.com
-```
-
-You can also specify the screen size for the screenshot with `width` and `height` parameters.
-
-```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
-```
-
-You can describe the interaction that you want to have with the webpage before taking a screenshot in JavaScript.
-
-```rst
-.. screenshot:: http://www.example.com
-
-  document.querySelector('button').click();
-```
-
-## Pro tips
-`sphinxcontrib-screenshot` supports URLs with the HTTP and HTTPS protocols.
-To take screenshots of local files and build the document while running a local server for them, you can use the NPM library [concurrently](https://www.npmjs.com/package/concurrently) in the following way:
-
-### Build the document
-```bash
-  npx --yes concurrently -k --success=first "make html" "python3 -m http.server 3000 --directory=examples"
-```
-
-### Watch and build the document
-```bash
-  npx --yes concurrently -k "make livehtml" "python3 -m http.server 3000 --directory=examples"
-```
-
-
-## Notes
-
-This extension uses [Playwright](https://playwright.dev) to capture a screenshot of the specified website only.
-No data is sent to any other external server; the request is limited to the specified website.
-Be cautious: avoid including sensitive information (such as authentication data) in the directive content.
-
-## Contributing
-
-See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.
-
-## License
-
-Apache 2.0; see [`LICENSE`](LICENSE) for details.
-
-## Disclaimer
-
-This project is not an official Google project. It is not supported by
-Google and Google specifically disclaims all warranties as to its quality,
-merchantability, or fitness for a particular purpose.

sphinxcontrib_screenshot-0.1.3/setup.cfg

@@ -1,60 +0,0 @@
-[metadata]
-name = sphinxcontrib-screenshot
-version = attr: sphinxcontrib.screenshot.__version__
-description = A Shpinx extension to embed webpage screenshots.
-long_description = file: README.md
-long_description_content_type = text/markdown
-license = Apache-2.0
-author = Shuhei Iitsuka
-author_email = tushuhei@gmail.com
-url = https://github.com/tushuhei/sphinxcontrib-screenshot/
-classifiers = 
-	Development Status :: 3 - Alpha
-	Operating System :: OS Independent
-	License :: OSI Approved :: Apache Software License
-	Programming Language :: Python :: 3.9
-	Programming Language :: Python :: 3.10
-	Programming Language :: Python :: 3.11
-
-[options]
-python_requires = >= 3.9
-packages = 
-	sphinxcontrib
-include_package_data = True
-test_suite = tests
-install_requires = 
-	playwright
-	sphinx
-
-[options.extras_require]
-dev = 
-	beautifulsoup4
-	build
-	flake8
-	isort
-	mypy
-	Pillow
-	pytest
-	sphinx[test]
-	toml
-	twine
-	types-beautifulsoup4
-	types-docutils
-	types-Pillow
-	types-setuptools
-	yapf
-
-[yapf]
-based_on_style = yapf
-
-[flake8]
-indent-size = 2
-
-[mypy]
-python_version = 3.9
-pretty = True
-
-[egg_info]
-tag_build = 
-tag_date = 0
-