settingsLogin | Registersettings

[openstack-dev] [infra] support graphviz in document publishing

0 votes

Hi, all

Sometimes a picture worths thousands word. I wonder if it is possible to
support graphviz in https://docs.openstack.org/

What I expect is to include a dot file and render it as a picture in HTML
output. The syntax is simple

.. graphviz:: aggregate-equivalent-alarms.files/example.dot

And should be supported by sphinx graphviz plugin2

See full example1. Currently I render the picture offline and include it
manually in the document. It would be much more convenient for developer if
the extension is added to document build job.

--
Yujun Zhang


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
asked Nov 13, 2017 in openstack-dev by Zhang_Yujun (3,760 points)   2 2

6 Responses

0 votes

On 2017-11-13 10:16, Yujun Zhang (ZTE) wrote:
Hi, all

Sometimes a picture worths thousands word. I wonder if it is possible to
support graphviz in https://docs.openstack.org/

What I expect is to include a dot file and render it as a picture in
HTML output. The syntax is simple

.. graphviz:: aggregate-equivalent-alarms.files/example.dot

And should be supported by sphinx graphviz plugin[2]

See full example[1]. Currently I render the picture offline and include
it manually in the document. It would be much more convenient for
developer if the extension is added to document build job.

You can easily include them for any repository - add the python
requirements to test-requirments and add the binary requirements to
bindep.txt - as explained in
https://docs.openstack.org/infra/manual/drivers.html#package-requirements

Andreas

[1]:
https://review.openstack.org/#/c/518196/5/proposals/aggregate-equivalent-alarms.rst
[2]: http://www.sphinx-doc.org/en/stable/ext/graphviz.html

--
Yujun Zhang


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 13, 2017 by Andreas_Jaeger (17,140 points)   2 3 3
0 votes

On Mon, Nov 13, 2017 at 09:16:59AM +0000, Yujun Zhang (ZTE) wrote:
Hi, all

Sometimes a picture worths thousands word. I wonder if it is possible to
support graphviz in https://docs.openstack.org/

What I expect is to include a dot file and render it as a picture in HTML
output. The syntax is simple

.. graphviz:: aggregate-equivalent-alarms.files/example.dot

And should be supported by sphinx graphviz plugin[2]

Hey Yujun,

The graphviz directive is currently supported [0]. Though the control over the
output leaves a little to be desired [1].

I'm not sure about referencing dotfiles, but most needs are fairly small and
can be done inline like the example above.

[0] https://git.openstack.org/cgit/openstack/cinder/tree/doc/source/contributor/api_microversion_dev.rst#n81
[1] https://docs.openstack.org/cinder/latest/contributor/api_microversion_dev.html


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 13, 2017 by Sean_McGinnis (11,820 points)   2 2 5
0 votes

The Octavia project has a few graphviz diagrams in it's documentation.
You can reference that project to see how it is done.
That said, we have seen a decline in the stability of the graphviz
code over the last few years (cylinder object disappeared, graphviz
dot crashes on Ubuntu, etc.) that we have had to work around to get
the diagrams to continue to render. Because of that I would recommend
you use it sparingly.

Michael

On Mon, Nov 13, 2017 at 2:08 AM, Sean McGinnis sean.mcginnis@gmx.com wrote:
On Mon, Nov 13, 2017 at 09:16:59AM +0000, Yujun Zhang (ZTE) wrote:

Hi, all

Sometimes a picture worths thousands word. I wonder if it is possible to
support graphviz in https://docs.openstack.org/

What I expect is to include a dot file and render it as a picture in HTML
output. The syntax is simple

.. graphviz:: aggregate-equivalent-alarms.files/example.dot

And should be supported by sphinx graphviz plugin[2]

Hey Yujun,

The graphviz directive is currently supported [0]. Though the control over the
output leaves a little to be desired [1].

I'm not sure about referencing dotfiles, but most needs are fairly small and
can be done inline like the example above.

[0] https://git.openstack.org/cgit/openstack/cinder/tree/doc/source/contributor/api_microversion_dev.rst#n81
[1] https://docs.openstack.org/cinder/latest/contributor/api_microversion_dev.html


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 13, 2017 by Michael_Johnson (4,380 points)   4 5
0 votes

On 13/11/2017 10:16, Yujun Zhang (ZTE) wrote:
Hi, all

Sometimes a picture worths thousands word. I wonder if it is possible to
support graphviz in https://docs.openstack.org/

What I expect is to include a dot file and render it as a picture in
HTML output. The syntax is simple

.. graphviz:: aggregate-equivalent-alarms.files/example.dot

And should be supported by sphinx graphviz plugin[2]

See full example[1]. Currently I render the picture offline and include
it manually in the document. It would be much more convenient for
developer if the extension is added to document build job.

[1]:
https://review.openstack.org/#/c/518196/5/proposals/aggregate-equivalent-alarms.rst
[2]: http://www.sphinx-doc.org/en/stable/ext/graphviz.html

Hello,

I had some success with http://blockdiag.com/ which, IIRC, is pure
python. It supports various kind of graphs (block, sequences, network ...).

The few I did were for Zuul:
https://docs.openstack.org/infra/zuul/user/gating.html

In sphinx that looks like:

.. blockdiag::

blockdiag foo {
nodewidth = 40;
span
width = 40;
A <- B <- C <- D <- E;
}

sphinxcontrib-blockdiag
https://pypi.python.org/pypi/sphinxcontrib-blockdiag

Might be worth looking at if you want something simpler than graphviz
and to not depend on it.

--
Antoine "hashar" Musso


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 13, 2017 by Antoine_Musso (280 points)   1
0 votes

On Mon, Nov 13, 2017 at 5:41 PM Andreas Jaeger aj@suse.com wrote:

You can easily include them for any repository - add the python
requirements to test-requirments and add the binary requirements to
bindep.txt - as explained in
https://docs.openstack.org/infra/manual/drivers.html#package-requirements

Thanks Andreas.

Besides the dependency you mentioned, I just realized that we need also to
add the extension to sphinx conf[1] to make it effective.

https://review.openstack.org/#/c/518196/8/doc/source/conf.py
--
Yujun Zhang


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 14, 2017 by Zhang_Yujun (3,760 points)   2 2
0 votes

On Tue, Nov 14, 2017 at 5:05 AM Antoine Musso hashar@free.fr wrote:

Hello,

I had some success with http://blockdiag.com/ which, IIRC, is pure
python. It supports various kind of graphs (block, sequences, network ...).

The few I did were for Zuul:
https://docs.openstack.org/infra/zuul/user/gating.html

In sphinx that looks like:

.. blockdiag::

blockdiag foo {
nodewidth = 40;
span
width = 40;
A <- B <- C <- D <- E;
}

sphinxcontrib-blockdiag
https://pypi.python.org/pypi/sphinxcontrib-blockdiag

Might be worth looking at if you want something simpler than graphviz
and to not depend on it.

Really nice diagram and syntax. I will surely consider it for some workflow
in the specification.

Thank you for the recommendation, Antoine

--
Yujun Zhang


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Nov 14, 2017 by Zhang_Yujun (3,760 points)   2 2
...