Installation

This extension can be installed with:

pip install sphinx_k3d_screenshot

or with:

conda install -c davide_sd sphinx_k3d_screenshot

It will install the following requirements: k3d, selenium, webdriver_manager, sphinx, pillow.

The screenshots will be created with some headless web browser. However, no browser and no driver will be installed by this extension. That’s left to the user.

Configuring the extension

The configuration depends on the machine in which the extension will be executed.

The extension uses selenium to automate the process of generating screenshots, which requires a web browser and a driver. User needs to install the intended browser (Firefox or Chrome) and the respective driver (geckodriver or webdriver )

If the extension is going to be executed on a readthedocs.org server, then setting up the browser and driver can be done by customizing the build. For example, the .readthedocs.yml used by this extension is:

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

build:
   os: ubuntu-22.04
   tools:
      python: "3.9"
   apt_packages:
      # dependencies for firefox
      - bzip2
      - libxtst6
      - libgtk-3-0
      - libx11-xcb-dev
      - libdbus-glib-1-2
      - libxt6
      - libpci-dev
      - libasound2
   jobs:
      pre_install:
         - mkdir $HOME/selenium
         - mkdir $HOME/selenium/drivers
         # chrome
         - wget -N https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F1047731%2Fchrome-linux.zip\?generation\=1663284576100523\&alt\=media -P $HOME
         - unzip ~/Linux_x64%2F1047731%2Fchrome-linux.zip\?generation=1663284576100523\&alt=media -d $HOME/selenium
         - rm ~/Linux_x64%2F1047731%2Fchrome-linux.zip\?generation=1663284576100523\&alt=media
         - wget -N https://chromedriver.storage.googleapis.com/107.0.5304.62/chromedriver_linux64.zip -P $HOME
         - unzip ~/chromedriver_linux64.zip -d $HOME/selenium/drivers
         - rm ~/chromedriver_linux64.zip
         # firefox
         - wget -N "http://download-origin.cdn.mozilla.net/pub/firefox/releases/105.0b9/linux-x86_64/en-US/firefox-105.0b9.tar.bz2" -P $HOME/selenium
         - tar xfj $HOME/selenium/firefox-105.0b9.tar.bz2 -C $HOME/selenium
         - rm $HOME/selenium/firefox-105.0b9.tar.bz2
         - wget -N https://github.com/mozilla/geckodriver/releases/download/v0.32.0/geckodriver-v0.32.0-linux64.tar.gz -P $HOME
         - tar -xvzf $HOME/geckodriver-v0.32.0-linux64.tar.gz -C $HOME/selenium/drivers
         - rm $HOME/geckodriver-v0.32.0-linux64.tar.gz

# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/source/conf.py

# Optionally build your docs in additional formats such as PDF
# formats:
#    - pdf

# Optionally set the version of Python and requirements required to build your docs
python:
   install:
   - requirements: docs/requirements.txt
   - method: pip
     path: .
   - method: pip
     path: .
     extra_requirements:
        - dev

Then, on the documentation’s conf.py we can set the following variables:

import os

# Select the browser. If omitted, Chrome will be used.
k3d_screenshot_browser = "chrome" # "chrome" or "firefox"

# Paths to the executables. If omitted, selenium will attempt to run
# the executables from the system $PATH.
# The paths must match the ones created on .readthedocs.yml
home_folder = os.path.expanduser("~")
k3d_screenshot_browser_path = os.path.join(home_folder, "selenium/chrome-linux/chrome")
k3d_screenshot_driver_path = os.path.join(home_folder, "selenium/drivers/chromedriver")
# run browser in headless mode
k3d_screenshot_driver_options = ["--headless"]