Reputation: 6285
I'm trying to add programmatically-rendered diagrams to my reStructuredText documentation, which I render to HTML with Sphinx.
Per https://lpn-doc-sphinx-primer-devel.readthedocs.io/extensions/blockdiag/blockdiag.html , I've added sphinxcontrib-blockdiag
to conf.py:
# conf.py
...
extensions = [
'sphinxcontrib.blockdiag',
]
...
Per http://blockdiag.com/en/blockdiag/sphinxcontrib.html, I've installed sphinxcontrib-blockdiag
with pip
:
$ pip install sphinxcontrib-blockdiag
...
$ pip freeze
...
blockdiag==3.0.0
...
sphinxcontrib-blockdiag==3.0.0
...
I created a .rst
file with the example from http://blockdiag.com/en/blockdiag/sphinxcontrib.html verbatim:
A Heading
=========
Some text before the diagram.
.. blockdiag::
blockdiag admin {
top_page -> config -> config_edit -> config_confirm -> top_page;
}
Some text after the diagram.
The resulting HTML renders with no diagram. When I open the rendered HTML in my browser, it essentially looks like this:
A Heading
Some text before the diagram.
Some text after the diagram.
How do I make the blockdiag/Sphinx integration work as advertised? How can I get whatever parts of the software pipeline to perform as claimed and include a diagram in the rendered HTML?
Below is the sphinx-build ./source/ ./build/
output -- note the warning about a "textsize" attribute:
$ sphinx-build ./source/ ./build/
Running Sphinx v7.2.6
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
WARNING: dot code 'blockdiag admin {\n top_page -> config -> config_edit -> config_confirm -> top_page;\n}': 'ImageDraw' object has no attribute 'textsize'
generating indices... genindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.
The HTML pages are in build.
$
Note that the official documentation example at http://blockdiag.com/en/blockdiag/sphinxcontrib.html does not mention any "textsize" attribute, so I assumed this was an ignorable warning.
Moreover, searching the official documentation site for "textsize" yields no hits.
Just for kicks, I tried sticking a guessed-at textsize
option in the .. blockdiag::
section of index.rst
:
A Heading
=========
Some text before the diagram.
.. blockdiag::
:textsize: 5
blockdiag admin {
top_page -> config -> config_edit -> config_confirm -> top_page;
}
Some text after the diagram.
...this generated an outright error with sphinx-build
:
/home/user/dev/scratch/sphinx-blockdiag/source/index.rst:27: ERROR: Error in "blockdiag" directive:
unknown option: "textsize".
.. blockdiag::
:textsize: 5
blockdiag admin {
top_page -> config -> config_edit -> config_confirm -> top_page;
}
Upvotes: 0
Views: 56