README.md

gmic-sphinx

A Sphinx extension for displaying G'MIC command results as images using the gmic-py Python binding.

Usage

This Sphinx extension adds a new directive name gmicpic that takes any gmic expression as input and outputs an image and the gmic command below as caption (other could come later). It has been tested with Sphinx's html builder only for now.

It works only with the reStructuredText (aka ReST) documentation format, not Markdown or others.

In any of your .rst file, add the following:

.. gmicpic:: your gmic command

For example:

.. gmicpic:: sp earth blur 4 output earthy.png

will yield a picture file-named earthy.png followed by the command as caption:

sp earth blur 4 output earthy.png

G'MIC command pre-processing

1. that the output parameter is optional.
2. In order to prevent proxy-blocking issues at docs build-time, G'MIC's samples are stored in this extension:

.. gmicpic:: sp leno blur 4

will yield a picture file-named with a unique id cce2fce2-e6fc-11ea-9e0e-8cec4b8c0881.png followed by the command as caption:

sp leno blur 4

...implies that leno.png exists in the gmic_samples directory (we have done it for you for <=2020 image samples already). The resulting implicit output image will be pre-stored in gmic-images/ with a unique-id generated .png filename.

Installing & set-up

Install this Python module from pypi.org (in the same virtual environment as Sphinx):

pip install gmic-sphinx

Edit your Sphinx documentation project's conf.py file and ensure you have line like:

extensions = ['gmic-sphinx']

You might need to add gmic-sphinx to your Python path.

Projects using this

This extension is used in the following projects:

• gmic-py // readthedocs.io documentation
• PR to add your project here :)

Tests

Automated pytest test cases are run in the Github Actions tab. You can run them yourself as well in a Python >= 3.7 environment.

Install the test requirements:

pip install dev-requirements.txt

Install the package locally:

pip install .

Run the pytest test suite:

py.test tests/

Releasing

If you are maintainer and would like to trigger a new release for this project, you do not need any credential since they are stored as Github Secret for this project. You just have:

1. Change the version number in gmic_sphinx/gmicpic.py's setup() function and gmic_sphinx/gmicpic.py's setup() function.
2. to Git-push a new tag, as described in this Github Action Worfklow file.

License

This project is under the CeCILL License.