|
2 | 2 | A directive for including a Matplotlib plot in a Sphinx document |
3 | 3 | ================================================================ |
4 | 4 |
|
5 | | -By default, in HTML output, `plot` will include a .png file with a link to a |
6 | | -high-res .png and .pdf. In LaTeX output, it will include a .pdf. |
| 5 | +This is a Sphinx extension providing a reStructuredText directive |
| 6 | +``.. plot::`` for including a plot in a Sphinx document. |
7 | 7 |
|
8 | | -The source code for the plot may be included in one of three ways: |
| 8 | +In HTML output, ``.. plot::`` will include a .png file with a link |
| 9 | +to a high-res .png and .pdf. In LaTeX output, it will include a .pdf. |
| 10 | +
|
| 11 | +The plot content may be defined in one of three ways: |
9 | 12 |
|
10 | 13 | 1. **A path to a source file** as the argument to the directive:: |
11 | 14 |
|
|
28 | 31 | .. plot:: |
29 | 32 |
|
30 | 33 | import matplotlib.pyplot as plt |
31 | | - import matplotlib.image as mpimg |
32 | | - import numpy as np |
33 | | - img = mpimg.imread('_static/stinkbug.png') |
34 | | - imgplot = plt.imshow(img) |
| 34 | + plt.plot([1, 2, 3], [4, 5, 6]) |
| 35 | + plt.title("A plotting exammple") |
35 | 36 |
|
36 | 37 | 3. Using **doctest** syntax:: |
37 | 38 |
|
|
44 | 45 | Options |
45 | 46 | ------- |
46 | 47 |
|
47 | | -The ``plot`` directive supports the following options: |
| 48 | +The ``.. plot::`` directive supports the following options: |
48 | 49 |
|
49 | | - format : {'python', 'doctest'} |
| 50 | + ``:format:`` : {'python', 'doctest'} |
50 | 51 | The format of the input. If unset, the format is auto-detected. |
51 | 52 |
|
52 | | - include-source : bool |
| 53 | + ``:include-source:`` : bool |
53 | 54 | Whether to display the source code. The default can be changed using |
54 | | - the `plot_include_source` variable in :file:`conf.py` (which itself |
| 55 | + the ``plot_include_source`` variable in :file:`conf.py` (which itself |
55 | 56 | defaults to False). |
56 | 57 |
|
57 | | - encoding : str |
| 58 | + ``:encoding:`` : str |
58 | 59 | If this source file is in a non-UTF8 or non-ASCII encoding, the |
59 | 60 | encoding must be specified using the ``:encoding:`` option. The |
60 | 61 | encoding will not be inferred using the ``-*- coding -*-`` metacomment. |
61 | 62 |
|
62 | | - context : bool or str |
| 63 | + ``:context:`` : bool or str |
63 | 64 | If provided, the code will be run in the context of all previous plot |
64 | 65 | directives for which the ``:context:`` option was specified. This only |
65 | 66 | applies to inline code plot directives, not those run from files. If |
|
68 | 69 | running the code. ``:context: close-figs`` keeps the context but closes |
69 | 70 | previous figures before running the code. |
70 | 71 |
|
71 | | - nofigs : bool |
| 72 | + ``:nofigs:`` : bool |
72 | 73 | If specified, the code block will be run, but no figures will be |
73 | 74 | inserted. This is usually useful with the ``:context:`` option. |
74 | 75 |
|
75 | | - caption : str |
| 76 | + ``:caption:`` : str |
76 | 77 | If specified, the option's argument will be used as a caption for the |
77 | 78 | figure. This overwrites the caption given in the content, when the plot |
78 | 79 | is generated from a file. |
79 | 80 |
|
80 | | -Additionally, this directive supports all of the options of the `image` |
81 | | -directive, except for *target* (since plot will add its own target). These |
82 | | -include *alt*, *height*, *width*, *scale*, *align* and *class*. |
| 81 | +Additionally, this directive supports all the options of the `image directive |
| 82 | +<https://docutils.sourceforge.io/docs/ref/rst/directives.html#image>`_, |
| 83 | +except for ``:target:`` (since plot will add its own target). These include |
| 84 | +``:alt:``, ``:height:``, ``:width:``, ``:scale:``, ``:align:`` and ``:class:``. |
83 | 85 |
|
84 | 86 | Configuration options |
85 | 87 | --------------------- |
|
0 commit comments