Skip to main content

A Shpinx extension to embed webpage screenshots.

Project description

sphinxcontrib-screenshot

A Sphinx extension to embed website screenshots.

Example screenshot

Install

pip install sphinxcontrib-screenshot
playwright install

Usage

Add sphinxcontrib.screenshot to your conf.py.

extensions = ["sphinxcontrib.screenshot"]

Then use the screenshot directive in your Sphinx source file.

.. screenshot:: http://www.example.com

You can also specify the screen size for the screenshot with width and height parameters.

.. screenshot:: http://www.example.com
  :width: 1280
  :height: 960

You can include a caption for the screenshot's figure directive.

.. 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.

.. 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 in the following way:

Build the document

  npx --yes concurrently -k --success=first "make html" "python3 -m http.server 3000 --directory=examples"

Watch and build the document

  npx --yes concurrently -k "make livehtml" "python3 -m http.server 3000 --directory=examples"

Notes

This extension uses Playwright 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 for details.

License

Apache 2.0; see 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib_screenshot-0.1.2.tar.gz (9.1 kB view hashes)

Uploaded Source

Built Distribution

sphinxcontrib_screenshot-0.1.2-py3-none-any.whl (9.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page