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

2017-11-14 Thread Yujun Zhang (ZTE) 
On Tue, Nov 14, 2017 at 5:05 AM Antoine Musso  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 {
> node_width = 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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-11-14 Thread Yujun Zhang (ZTE) 
On Mon, Nov 13, 2017 at 5:41 PM Andreas Jaeger  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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-11-13 Thread Antoine Musso 
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 {
node_width = 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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-11-13 Thread Michael Johnson 
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  wrote:
> On Mon, Nov 13, 2017 at 09:16:59AM +, 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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-11-13 Thread Sean McGinnis 
On Mon, Nov 13, 2017 at 09:16:59AM +, 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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-11-13 Thread Andreas Jaeger 
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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

2017-11-13 Thread Yujun Zhang (ZTE) 
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

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