Converting an arbitrary node to an image node at "visit-time"
Leandro Lucarella
I'm trying to improve the aafig_ Sphinx extension to use an image node
to output the aafigure_ generated image, so it can take advantage of the
extra image options (like height, width, etc.) and any bug-fixes.
Consistency is a nice advantage too.
The problem is I'm getting an error when doing that. I'm sorry about the
cross-posting, but I don't know if the error is docutils or Sphinx
related.
What I'm doing is something like::
def aafig_node_html_visit(self, node):
# generate the aafigure image
node.img = nodes.image()
# copy aafig attributes to the image node
self.visit_image(node.img)
raise nodes.SkipNode
def aafig_node_html_depart(self, node):
self.depart_image(node.img)
raise nodes.SkipNode
I don't really know if it's ok to skip the node (I just had another error
without the raise nodes.SkipNode).
The error I'm getting is::
Traceback (most recent call last):
File "/usr/lib/pymodules/python2.5/sphinx/cmdline.py", line 172, in main
app.build(all_files, filenames)
File "/usr/lib/pymodules/python2.5/sphinx/application.py", line 130, in build
self.builder.build_update()
File "/usr/lib/pymodules/python2.5/sphinx/builders/__init__.py", line 265, in build_update
'out of date' % len(to_build))
File "/usr/lib/pymodules/python2.5/sphinx/builders/__init__.py", line 320, in build
self.write(docnames, list(updated_docnames), method)
File "/usr/lib/pymodules/python2.5/sphinx/builders/__init__.py", line 359, in write
self.write_doc(docname, doctree)
File "/usr/lib/pymodules/python2.5/sphinx/builders/html.py", line 343, in write_doc
self.docwriter.write(doctree, destination)
File "/usr/lib/pymodules/python2.5/docutils/writers/__init__.py", line 76, in write
self.translate()
File "/usr/lib/pymodules/python2.5/sphinx/writers/html.py", line 37, in translate
self.document.walkabout(visitor)
File "/usr/lib/pymodules/python2.5/docutils/nodes.py", line 189, in walkabout
visitor.dispatch_departure(self)
File "/usr/lib/pymodules/python2.5/docutils/nodes.py", line 1548, in dispatch_departure
return method(node)
File "/usr/lib/pymodules/python2.5/docutils/writers/html4css1/__init__.py", line 712, in depart_document
assert not self.context, 'len(context) = %s' % len(self.context)
AssertionError: len(context) = 15
I'm doing something wrong? Any ideas how to do that? I can't "emit" an
image node at "parse-time" because I don't know yet what builder will be
used to pick the right output format for aafig.
TIA.
.. _aafig:: http://pypi.python.org/pypi/sphinxcontrib-aafig
.. _aafigure:: https://launchpad.net/aafigure
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
You look so tired-unhappy,
bring down the government,
they don't, they don't speak for us.
Leandro Lucarella
> Hi.
>
> I'm trying to improve the aafig_ Sphinx extension to use an image node
> to output the aafigure_ generated image, so it can take advantage of the
> extra image options (like height, width, etc.) and any bug-fixes.
> Consistency is a nice advantage too.
>
> The problem is I'm getting an error when doing that. I'm sorry about the
> cross-posting, but I don't know if the error is docutils or Sphinx
> related.
>
> What I'm doing is something like::
>
> def aafig_node_html_visit(self, node):
> # generate the aafigure image
> node.img = nodes.image()
> # copy aafig attributes to the image node
> self.visit_image(node.img)
> raise nodes.SkipNode
>
> def aafig_node_html_depart(self, node):
> self.depart_image(node.img)
> raise nodes.SkipNode
I took a different approach trying to do this. I saw how the figure
directive is implemented and I decided to give that way a try. It's all
almost working, but I have a small problem and I don't know how to fix it,
if it's even possible without modifying docutils/Sphinx.
What I'm doing is inherit my Aafig directive from docutil's Image and
create an image in a similar way as the Figure directive does.
This is the simplified code:
class Aafig(directives.images.Image):
def run(self):
self.arguments = ['???'] # (1)
(image_node,) = directives.images.Image.run(self)
aafig_node = aafig(text, image_node, **aafig_options)
return [aafig_node]
def aafig_html_visit(self, node):
# generate the image
image_node = node[0]
image_node['src'] = image_file_path # (2)
My problem is, I don't know the file name of the image at point (1)
because the image file name depends on the builder used to render the
document. As things are now, I have to add the argument to the directive
because the Image directive expects one argument, but I don't know what's
the image file name until (2). I can't come up with a format-independent
image file name because I have to store the generated image in the build
directory, which is builder-dependent.
Is there any way to do what I want? If not, will you be willing to accept
patches to allow this? I think other extensions can benefit from this,
like the official graphviz extension (in which I based the aafig
extension) and my other graphviz-based extension: mscgen.
TIA.
Leandro Lucarella
> > Is there any way to do what I want?
>
> pending node during the parsing step and define a `transform` to convert
> this into an image node. The transform can find out which writer/builder
> is in use [#]_ and set the URL accordingly.
Ok, this looks much cleaner. Thanks.
> .. [#] It can, e.g. test document.settings for the existence of
> writer-specific settings. Maybe there is an even better way.
This point is crucial for me. Is there any way to identify which
writer/builder is used when transforming? A setting is not good, because
a single Sphinx document/config is used to render to to both HTML and
LaTeX (and possibly more formats). Unless I can access to command line
options (The format to render to is passed as a command line option).
> > If not, will you be willing to accept patches to allow this? I think
> > other extensions can benefit from this, like the official graphviz
> > extension (in which I based the aafig extension) and my other
> > graphviz-based extension: mscgen.
>
> Patches are fine -- even better if the match the `Docutils policies`__.
> Did you have a look how the graphviz extension does it?
It do it wrong =)
I based my extension on that. It defines a new kind of node and add add
new visit functions to render it. It generates the image file when
rendering and use custom code to render (it writes it own HTML/LaTeX).
If I find a solution for this, I plan to update the graphviz extension
too.
Thanks.
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
Pa' ella cociné, pa' ella lavé, pa' ella soñe
Paella completa, $2,50
Pero, la luz mala me tira, y yo? yo soy ligero pa'l trote
La luz buena, está en el monte, allá voy, al horizonte
Leandro Lucarella
>
> pending node during the parsing step and define a `transform` to convert
> this into an image node. The transform can find out which writer/builder
> is in use [#]_ and set the URL accordingly.
Ok, this looks much cleaner. Thanks.
> .. [#] It can, e.g. test document.settings for the existence of
> writer-specific settings. Maybe there is an even better way.
This point is crucial for me. Is there any way to identify which
writer/builder is used when transforming? A setting is not good, because
a single Sphinx document/config is used to render to to both HTML and
LaTeX (and possibly more formats). Unless I can access to command line
options (The format to render to is passed as a command line option).
> > If not, will you be willing to accept patches to allow this? I think
> > other extensions can benefit from this, like the official graphviz
> > extension (in which I based the aafig extension) and my other
> > graphviz-based extension: mscgen.
>
> Patches are fine -- even better if the match the `Docutils policies`__.
> Did you have a look how the graphviz extension does it?
It do it wrong =)
I based my extension on that. It defines a new kind of node and add add
new visit functions to render it. It generates the image file when
rendering and use custom code to render (it writes it own HTML/LaTeX).
If I find a solution for this, I plan to update the graphviz extension
too.
Thanks.
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
Leandro Lucarella
> On Thu, Jun 25, 2009 at 20:15, Leandro Lucarella<llu...@gmail.com> wrote:
> > Is there any way to do what I want?
>
> a transform to do the work. For an example of delayed processing, see
> the "contents" directive and associated transform.
>
> The writer (what you call a "builder") should not be doing any
Sphinx has a builder too, I don't know what's the difference with the
writer and what it's exactly for though.
> transforms to the document tree. It shouldn't be adding or changing
> any nodes. The writer's job is to translate the document tree into
> output, and that's it. Use a transform to do tree manipulations.
Sounds fair, but I need to know what writer will be used when doing the
transformation. Is that possible? How? I can't find any code doing that.
> > If not, will you be willing to accept
> > patches to allow this?
>
> Only if they fix real bugs or deficiencies. I don't think there are any
> here.
I hope you are right =)
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
Es mucho mas probable que el salchichón sea primavera a que la primavera
sea salchichón.
-- Peperino Pómoro
Leandro Lucarella
> On Thu, Jun 25, 2009 at 20:15, Leandro Lucarella<llu...@gmail.com> wrote:
>
> a transform to do the work. For an example of delayed processing, see
> the "contents" directive and associated transform.
>
> The writer (what you call a "builder") should not be doing any
Sphinx has a builder too, I don't know what's the difference with the
writer and what it's exactly for though.
> transforms to the document tree. It shouldn't be adding or changing
> any nodes. The writer's job is to translate the document tree into
> output, and that's it. Use a transform to do tree manipulations.
Sounds fair, but I need to know what writer will be used when doing the
transformation. Is that possible? How? I can't find any code doing that.
> > If not, will you be willing to accept
> > patches to allow this?
>
> Only if they fix real bugs or deficiencies. I don't think there are any
> here.
I hope you are right =)
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
Leandro Lucarella
> In Docutils, any writer can add command-line-options/config settings, and
> the config-file has writer-specific sections. The transform has access to
> the 'document' object which has a 'document.settings' argument which is
> already populated with the writer-dependend settings, e.g. since the last
> commit, class SectNum(Transform) in parts.py contains writer-dependent
> code (as LaTeX can generate section numbers)::
>
> def apply(self):
> try: # leave section numbering to the writer?
> numbering_by_writer = self.document.settings.use_latex_toc
> except AttributeError:
> numbering_by_writer = False
> # ...
>
> You'll have to ask Georg about the situation in Sphinx -- conf.py has
> just a comment telling that some settings are for LateX.
Mmm, ok. I did some hacking to peek at self.document.settings when
rendering using the HTML writer and the LaTeX writer and it seems that the
first one has at least an option (stylesheet_path) that the other doesn't
have.
Checking the presence of that setting could do the trick, but I find it
really dirty and fragile. =/
> > > Did you have a look how the graphviz extension does it?
>
> > It dos it wrong =)
>
> > I based my extension on that. It defines a new kind of node and add add
> > new visit functions to render it. It generates the image file when
> > rendering and use custom code to render (it writes it own HTML/LaTeX).
>
> But the image generation should be output-dependend too: there is no
> vector format supported by both HTML and LaTeX (or you generate SVG first
> and convert to EPS or PDF either in the tranform or with a latex wrapper
> like `rubber`.
It is output-dependent, that's why it's done at "visit-time" when the
writer is know (I don't know how the Sphinx extension mechanism works in
detail but I think it's done by the writer).
> But still, doing this in a transforms seems the way to go.
Yes, except that the writer-detection when transforming seems to be
a little... weak.
> You could also let the frontend add different tranforms (with a common
> base class, of course) for the different output formats.
I don't know how to do that. To be honest, I don't understand very well
how transforming work either, even when I read some code and the PEP
describing the design of Docutils =/
I guess I'll have to dig a little more. It's too sad that the project
lacks some more documentation, because is really great, but it takes quite
some time and effort to understand how it works.
Thanks.
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
Ya ni el cielo me quiere, ya ni la muerte me visita
Ya ni el sol me calienta, ya ni el viento me acaricia
Leandro Lucarella
> In Docutils, any writer can add command-line-options/config settings, and
> the config-file has writer-specific sections. The transform has access to
> the 'document' object which has a 'document.settings' argument which is
> already populated with the writer-dependend settings, e.g. since the last
> commit, class SectNum(Transform) in parts.py contains writer-dependent
> code (as LaTeX can generate section numbers)::
>
> def apply(self):
> try: # leave section numbering to the writer?
> numbering_by_writer = self.document.settings.use_latex_toc
> except AttributeError:
> numbering_by_writer = False
> # ...
>
> You'll have to ask Georg about the situation in Sphinx -- conf.py has
> just a comment telling that some settings are for LateX.
Mmm, ok. I did some hacking to peek at self.document.settings when
rendering using the HTML writer and the LaTeX writer and it seems that the
first one has at least an option (stylesheet_path) that the other doesn't
have.
Checking the presence of that setting could do the trick, but I find it
really dirty and fragile. =/
> > > Did you have a look how the graphviz extension does it?
>
> > It dos it wrong =)
>
> > I based my extension on that. It defines a new kind of node and add add
> > new visit functions to render it. It generates the image file when
> > rendering and use custom code to render (it writes it own HTML/LaTeX).
>
> But the image generation should be output-dependend too: there is no
> vector format supported by both HTML and LaTeX (or you generate SVG first
> and convert to EPS or PDF either in the tranform or with a latex wrapper
> like `rubber`.
It is output-dependent, that's why it's done at "visit-time" when the
writer is know (I don't know how the Sphinx extension mechanism works in
detail but I think it's done by the writer).
> But still, doing this in a transforms seems the way to go.
Yes, except that the writer-detection when transforming seems to be
a little... weak.
> You could also let the frontend add different tranforms (with a common
> base class, of course) for the different output formats.
I don't know how to do that. To be honest, I don't understand very well
how transforming work either, even when I read some code and the PEP
describing the design of Docutils =/
I guess I'll have to dig a little more. It's too sad that the project
lacks some more documentation, because is really great, but it takes quite
some time and effort to understand how it works.
Thanks.
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
Leandro Lucarella
> In Docutils, any writer can add command-line-options/config settings, and
> the config-file has writer-specific sections. The transform has access to
> the 'document' object which has a 'document.settings' argument which is
> already populated with the writer-dependend settings, e.g. since the last
> commit, class SectNum(Transform) in parts.py contains writer-dependent
> code (as LaTeX can generate section numbers)::
>
> def apply(self):
> try: # leave section numbering to the writer?
> numbering_by_writer = self.document.settings.use_latex_toc
> except AttributeError:
> numbering_by_writer = False
> # ...
>
> You'll have to ask Georg about the situation in Sphinx -- conf.py has
> just a comment telling that some settings are for LateX.
Mmm, ok. I did some hacking to peek at self.document.settings when
rendering using the HTML writer and the LaTeX writer and it seems that the
first one has at least an option (stylesheet_path) that the other doesn't
have.
Checking the presence of that setting could do the trick, but I find it
really dirty and fragile. =/
> > > Did you have a look how the graphviz extension does it?
>
> > It dos it wrong =)
>
> > I based my extension on that. It defines a new kind of node and add add
> > new visit functions to render it. It generates the image file when
> > rendering and use custom code to render (it writes it own HTML/LaTeX).
>
> But the image generation should be output-dependend too: there is no
> vector format supported by both HTML and LaTeX (or you generate SVG first
> and convert to EPS or PDF either in the tranform or with a latex wrapper
> like `rubber`.
It is output-dependent, that's why it's done at "visit-time" when the
writer is know (I don't know how the Sphinx extension mechanism works in
detail but I think it's done by the writer).
> But still, doing this in a transforms seems the way to go.
Yes, except that the writer-detection when transforming seems to be
a little... weak.
> You could also let the frontend add different tranforms (with a common
> base class, of course) for the different output formats.
I don't know how to do that. To be honest, I don't understand very well
how transforming work either, even when I read some code and the PEP
describing the design of Docutils =/
I guess I'll have to dig a little more. It's too sad that the project
lacks some more documentation, because is really great, but it takes quite
some time and effort to understand how it works.
Thanks.
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
Leandro Lucarella
> On Fri, Jun 26, 2009 at 20:37, Leandro Lucarella<llu...@gmail.com> wrote:
> > Sounds fair, but I need to know what writer will be used when doing the
> > transformation. Is that possible? How? I can't find any code doing that.
>
> http://docutils.sourceforge.net/docutils/transforms/components.py
>
> Within a transform, self.document.transformer.components['writer']
> will give you the writer object.
This is really nice, but... (there's always a but =) Sphinx seems to be
using a SphinxDummyWriter when transforming, no matter what the real
output format really is =/
All seems to be shaping out good using the Transform approach in the
docutils side, but I'm getting some Sphinx-specific problems. Besides the
dummy writer, I don't know if I can (and how) access to the builder when
implementing the Directive and Transform (I need to get some Sphinx
options from there)
I think I will need some Sphinx guidance to move on...
Thanks for your help. Docutils seems to be very well designed =)
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
Agarré, me fuí pal monte
Para ver el horizonte...
Leandro Lucarella
>
> David Goodger, el 27 de junio a las 17:52 me escribiste:
> > On Fri, Jun 26, 2009 at 20:37, Leandro Lucarella<llu...@gmail.com> wrote:
> > > Sounds fair, but I need to know what writer will be used when doing the
> > > transformation. Is that possible? How? I can't find any code doing that.
> >
> > See the Filter transform here:
> > http://docutils.sourceforge.net/docutils/transforms/components.py
> >
> > Within a transform, self.document.transformer.components['writer']
> > will give you the writer object.
>
> This is really nice, but... (there's always a but =) Sphinx seems to be
> using a SphinxDummyWriter when transforming, no matter what the real
> output format really is =/
>
> All seems to be shaping out good using the Transform approach in the
> docutils side, but I'm getting some Sphinx-specific problems. Besides the
> dummy writer, I don't know if I can (and how) access to the builder when
> implementing the Directive and Transform (I need to get some Sphinx
> options from there)
>
> I think I will need some Sphinx guidance to move on...
I'm hate to be insistent, but I'm really stuck with this. Does anyone know
how can I get what writer will be used (and the Sphinx builder object)
when doing a Docutils Transform?
Thanks.
Leandro Lucarella
> Leandro Lucarella, el 28 de junio a las 02:18 me escribiste:
> >
> > David Goodger, el 27 de junio a las 17:52 me escribiste:
> > > On Fri, Jun 26, 2009 at 20:37, Leandro Lucarella<llu...@gmail.com> wrote:
> > > > Sounds fair, but I need to know what writer will be used when doing the
> > > > transformation. Is that possible? How? I can't find any code doing that.
> > >
> > > See the Filter transform here:
> > > http://docutils.sourceforge.net/docutils/transforms/components.py
> > >
> > > Within a transform, self.document.transformer.components['writer']
> > > will give you the writer object.
> >
> > This is really nice, but... (there's always a but =) Sphinx seems to be
> > using a SphinxDummyWriter when transforming, no matter what the real
> > output format really is =/
> >
> > All seems to be shaping out good using the Transform approach in the
> > docutils side, but I'm getting some Sphinx-specific problems. Besides the
> > dummy writer, I don't know if I can (and how) access to the builder when
> > implementing the Directive and Transform (I need to get some Sphinx
> > options from there)
> >
> > I think I will need some Sphinx guidance to move on...
>
> I'm hate to be insistent, but I'm really stuck with this. Does anyone know
> how can I get what writer will be used (and the Sphinx builder object)
> when doing a Docutils Transform?
Ok, I finally got away with what I wanted by using a Sphinx event
(doctree-read) to render the image. The directive just created an image
node and add to it aafigure-specific information. When the event is
triggered, the doctree is traversed looking for image nodes with aafigure
information attached and process that nodes, rendering the images (and
applying other transformations if needed).
This worked out great and not the aafig extension get rendered as
a regular image, supporting all image options.
I hope this information can be useful...
I'll update the mscgen extension and the official graphviz extension to
use this scheme in the future.
You can peek at the code at:
http://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/aafig/sphinxcontrib/aafig.py
or download the dev package:
http://pypi.python.org/pypi/sphinxcontrib-aafig/0.3dev-20090702
A new release is comming soon, so testing is welcome =)
--
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
El techo de mi cuarto lleno de estrellas