sphinxcontrib-screenshot — A Sphinx extension to easily embed website screenshots

When creating documentation with Sphinx, there are many situations where you want to include screenshots of websites. However, manually taking screenshots, cropping them to the appropriate size, and managing the image files is a tedious process. Wouldn't it be nice if you could just specify the URL and image size, and have the image embedded automatically?

To reduce this hassle of screenshot management, I created a Sphinx extension called sphinxcontrib-screenshot. With this Sphinx extension, you can embed website screenshots into your documentation with simple markup.

Brief Feature Overview

sphinxcontrib-screenshot provides the following features:

• Automatic screenshot capture by URL: By simply specifying a URL, it automatically takes a screenshot using Playwright.
• Screen size customization: You can freely adjust the screenshot size by specifying the width and height parameters.
• Adding captions: You can add captions to the screenshots using the caption parameter.
• Automating page operations: You can write JavaScript in the directive body to perform operations before the screenshot is taken.
• Local file support: In addition to URLs, you can also specify the path to a local file to take a screenshot.

Installation

sphinxcontrib-screenshot is available on PyPI and can be easily installed with the following commands. The second command is to install the browsers used by Playwright.

pip install sphinxcontrib-screenshot
playwright install

Next, add sphinxcontrib.screenshot to your Sphinx project's conf.py.

extensions = ["sphinxcontrib.screenshot"]

Now you are ready to go.

Usage

Within your Sphinx source files, use the screenshot directive to specify the URL of the website you want to take a screenshot of.

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

You can also specify the size of the screenshot using the width and height parameters, or add a caption using the caption parameter.

.. screenshot:: http://www.example.com
   :width: 1280
   :height: 960
   :caption: This is a screenshot of www.example.com.

Furthermore, you can automate page operations before taking the screenshot by writing JavaScript.

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

   document.querySelector('button').click();

If you have common JavaScript code that you want to execute beforehand, you can also specify it as screenshot_init_script in conf.py.

Conclusion

sphinxcontrib-screenshot is an open-source project licensed under the Apache License 2.0. Detailed information and the source code are available on the following GitHub repository.

• GitHub: https://github.com/tushuhei/sphinxcontrib-screenshot
• PyPI: https://pypi.org/project/sphinxcontrib-screenshot/

sphinxcontrib-screenshot is a handy Sphinx extension that allows you to easily embed website screenshots into your Sphinx documentation. Please try installing it to streamline your documentation process!