qtgallery

========= qtgallery

.. image:: https://readthedocs.org/projects/qtgallery/badge/?version=latest :target: https://qtgallery.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status

Scraper for generating a sphinx-gallery_ of Qt widgets.

This repository serves both as a library for grabbing renderings of Qt widgets to add to your own sphinx-gallery config as well as an example of its usage.

Installation

For the time being, clone the repo and install from source::

$ git clone [e-mail]:ixjlyons/qtgallery.git
$ cd qtgallery
$ pip install .

Now you should be able to generate the docs/gallery::

$ cd doc
$ make html

Open up doc/_build/html/index.html to see built docs. They're currently being hosted by Read the Docs as well:

https://qtgallery.readthedocs.io/

Configuration

To use qtgallery in your own documentation, start by setting up sphinx-gallery. This library provides two key components to add to your sphinx_gallery_conf: an image scraper and a reset function_:

.. code-block:: python

sphinx conf.py

import qtgallery

sphinx_gallery_conf = { ... 'image_scrapers': (qtgallery.qtscraper, ...), 'reset_modules': (qtgallery.reset_qapp, ...), ... }

The image scraper is responsible for generating a rendering of all currently shown top level widgets.

The reset function is for handling QApplication, allowing you to instantiate the QApplication singleton in each example and preventing the Qt event loop from running and hanging the docs build. That is, examples that run ok standalone should behave ok in generating the gallery.

Usage

Usage pretty much follows sphinx-gallery, but one tip is that you can control where the widget/window is rendered via show(). See the iterative example to see how this works.

Read the Docs

On Read the Docs, xvfb is required. See their documentation for installing apt packages_. This repository also serves as an example (see .readthedocs.yml).

.. _sphinx-gallery: https://sphinx-gallery.github.io/stable/index.html .. _image scraper: https://sphinx-gallery.github.io/stable/configuration.html#image-scrapers .. _reset function: https://sphinx-gallery.github.io/stable/configuration.html#resetting-modules .. _iterative example: https://qtgallery.readthedocs.io/en/latest/auto_examples/iterative.html#sphx-glr-auto-examples-iterative-py .. _installing apt packages: https://docs.readthedocs.io/en/stable/config-file/v2.html#build-apt-packages