source file as argument to sphinx directive does not work

[jessetan]

On my local setup, using a Sphinx directive with content works, but not when given a filename as argument.

This works:

.. uml:: 

    @startuml
    bob->alice: hi
    @enduml

This doesn't:

.. uml:: mydiagram.puml

It looks like the directive content is a list of strings, which is converted to a single string with breaks using '\n'.join(content) before the call to render(). If a filename is given, it is read as a single string with linebreaks. Adding more linebreaks with '\n'.join(content) will send the following to the PlantUML server:

@
s
t
a
r
t
u
m
l
(etc)

The resulting png will complain about a syntax error.

It is possible that this is due to my local setup, but I'll file a quick MR in case I'm not the only one.

[jessetan]

@carlos-jenkins regarding your comment on the PR:

If I change directive.py to print the type and contents of self.content (diagram as directive content) and content (after file reading for diagram in a file) using the following RST input:

.. uml::

    @startuml
    bob->alice: hi
    @enduml

.. uml:: diagram.puml

the log is:

<type 'instance'>
[u'@startuml', u'bob->alice: hi', u'@enduml']
file
<type 'unicode'>
@startuml
bob->alice: hi
@enduml

So the directive content is a list of three strings. Calling '\n'.join() on it gives a single string with newlines. The file content is a single string with newlines. Calling '\n'.join() on it gives the behavior described in the issue.

Is this different from what you are seeing? I am running docutils 0.13.1 on Python 2.7.13.

The test does not fail for me, but it also doesn't check the contents of the output image (which is hard). If I copy the output files of the test to my desktop, the SVG files do not actually contain a diagram, but a syntax error, e.g. 30f77f041c05ea598dbaf50459703184f5c7f3ba4a3e070b2476482ca1235a9a.svg.zip

We are using the directive with argument a lot and it is working fine

I don't see any diagrams read from files in the doc directory, is there any example I can test here?

[carlos-jenkins]

Hi @jessetan

I was finally able to understand and reproduce the issue. You're right, the test doesn't fail, just returns an invalid image. I'm accepting your PR with the immediate, but I'll keep the issue open, as the render() call should fail if the image was unable to be rendered. Also, I need to improve the test test_directive_argument to account for this discover.

Thanks a lot.

[carlos-jenkins]

Fix for this issue was released in version 1.1.0. Thanks.

[jessetan]

the render() call should fail if the image was unable to be rendered. Also, I need to improve the test test_directive_argument to account for this discover

@carlos-jenkins Looks like PlantUML server returns one or more HTTP response headers X-PlantUML-Diagram-Error for bad diagrams, e.g. http://www.plantuml.com/plantuml/png/AqWiAibCpYp8Ar58v7BAJrBGLN3CoKnELR1Io4ZDoSa70000. You could look for it in each response and return an error from render() if it's there.

[carlos-jenkins]

@jessetan this is very important information, thank you very much. I'll try to allocate some time to code this. Thanks.