sphinx-plotly-directive

0.1.3 verified Fri May 01 auth: no python

A Sphinx directive for embedding Plotly figures in documentation. Current version 0.1.3, release cadence is low (last release Aug 2020).

pip install sphinx-plotly-directive

Common errors

error WARNING: directive plotly already registered. ↓

cause Another Sphinx extension also registers a 'plotly' directive (e.g., sphinxcontrib-plotly).

fix

Ensure only one extension providing 'plotly' is loaded in conf.py, or rename the directive via configuration (not exposed in this extension).

error Plotly figure not rendered in output (empty space or missing). ↓

cause The Python code inside the directive did not assign a variable named `fig`.

fix

Make sure the code block ends with fig assigned to a Plotly figure object.

error TypeError: __init__() got an unexpected keyword argument 'show_source' ↓

cause Incorrect option name; the directive option is `:show-source:` (with hyphen), not `:show_source:`.

fix

Use :show-source: in RST directive.

Warnings

gotcha The directive expects the Python code to assign a variable `fig` (the plotly figure). If no variable named `fig` is defined, nothing is rendered. ↓

fix Ensure the last line or the variable name is `fig` (or use `:show-source:` option, but still need fig).

gotcha When using with Sphinx 4+, there is a known issue with 'plotly' directive clashing if other plotly-related extensions are loaded. This can cause 'WARNING: directive plotly already registered'. ↓

fix Check for duplicate extension loading or use a different directive name via `plotly_plotly_directive_directive_name` option in conf.py (undocumented).

deprecated The extension has not been updated since 2020. Consider using sphinxcontrib-plotly or the newer nbsphinx for Plotly support. ↓

fix Migrate to sphinxcontrib-plotly or nbsphinx if you need active maintenance.

Imports

plotly directive

wrong

from sphinx_plotly_directive import ...

correct

No explicit import; activate via extensions = ['sphinx_plotly_directive'] in conf.py

It is a Sphinx extension, not a Python module to import in code.

Quickstart

Add the extension to conf.py, then use the .. plotly:: directive in RST.

# conf.py
extensions = [
    'sphinx_plotly_directive',
]

# index.rst
.. plotly::

    import plotly.graph_objects as go
    fig = go.Figure(data=go.Scatter(x=[1,2,3], y=[1,3,2]))
    fig