StoneThrow
StoneThrow

Reputation: 6285

How to get blockdiag directives rendered to HTML?

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

Answers (0)

Related Questions