search

blockdiag / seqdiag

Apache License 2.0
68 stars 14 forks source link

Limitations of use with Sphinx #9

Open tk0miya opened 6 years ago

tk0miya commented 6 years ago

I just made two tickets but closed them again because I wanted to file them against sphinxcontrib, but considering how the codebase is split up between these two projects in a pretty weird was I decided to file it here instead.

I had to stop using seqdiag in Sphinx for the following reasons:

  1. Does not provide me with a way to define the font size
  2. font maps are incredible hard to debug because they don't provide you with any debug output if it fails (all exceptions are silenced)
  3. SVG fonts are hardcoded to serif or sansserif (the latter not being a correct font definition for SVG so it falls back to serif)
  4. The metrics being wrong even if the font is set up properly when used with freetype2 and pillow on OS X (left pixel is hidden behind the shadow)
  5. shadows in SVG don't scale properly when the diagram is scaled down and there is no way to disable the shadow rendering either.
  6. font maps with invalid references cause a recursion error but no indication of where it happens because the traceback is hidden. You can see that a recursion is happening because it prints the "unknown font family" message a few thousand times.
  7. seqdiag (at least through sphinx) does not provide you with a way to lower the padding or add padding in places which makes it hard to use with a bigger diagram.

The closest to what I have come with getting the output work somewhat is this monkeypatch:

#!python
from blockdiag.imagedraw.svg import SVGImageDrawElement
from blockdiag.drawer import DiagramDraw

old_text = SVGImageDrawElement.text

def new_text(self, xy, string, font, **kwargs):
    font = font.duplicate()
    font.generic_family = 'Open Sans'
    font.font_size = 13
    xy = (xy[0] + 3, xy[1] - 3)
    return old_text(self, xy, string, font, **kwargs)

def new__draw_background(self):
    # Don't draw any background is you suck at it. srlsy
    pass

def setup(app):
    SVGImageDrawElement.text = new_text
    DiagramDraw._draw_background = new__draw_background
tk0miya commented 6 years ago

From Takeshi KOMIYA on 2011-07-29 17:28:11+00:00

Fixed in r861. It will fixed at next version (0.8.5).

tk0miya commented 6 years ago

From Armin Ronacher on 2012-08-21 11:54:01+00:00

(Screwed up the formatting horribly, don't use bitbucket much these days. Can I edit the issue somehow?)

Also I am happy to file individual bugs for it but I am not sure if this tracker is the correct place.

tk0miya commented 6 years ago

From Takeshi KOMIYA on 2012-08-22 06:38:49+00:00

Thank you for your advice :-)

  1. Does not provide me with a way to define the font size

default_fontsize attribute will help you.

seqdiag { default_fontsize = 18; A -> B [label = "GET /"] }

Or, fontsize attribute can change fontsize of specified element.

seqdiag { A -> B; A -> B [fontsize = 20]; }

  1. font maps are incredible hard to debug because they don't provide you with any debug output if it fails (all exceptions are silenced)
  2. font maps with invalid references cause a recursion error but no indication of where it happens because the traceback is hidden. You can see that a recursion is happening because it prints the "unknown font family" message a few thousand times.

Sorry, its design is my mistake. I'll add 'seqdiag_debug' option to sphinx and pass-through all exceptions.

  1. SVG fonts are hardcoded to serif or sansserif (the latter not being a correct font definition for SVG so it falls back to serif)

You have to use fontmaps to change font-family. On start-up seqdiag, any font-families (without serif) have not been defined, then you could not use them.

Please write fontmap file like this::

[fontmap] monospace = /usr/share/fonts/.../foo.ttf monospace-bold = /usr/share/fonts/.../bar.ttf

The font-family should be formed as generic_family_name .

Sorry for no docs about fontmaps ...

  1. The metrics being wrong even if the font is set up properly when used with freetype2 and pillow on OS X (left pixel is hidden behind the shadow)

I fixed it recently: https://bitbucket.org/tk0miya/seqdiag/changeset/bf7792210cbdf608b5674dc3cf1e76c059102108

  1. shadows in SVG don't scale properly when the diagram is scaled down and there is no way to disable the shadow rendering either.

I wonder how do you scale down the diagram?

BTW, disabling shadows feature is implemented on next release.

  1. seqdiag (at least through sphinx) does not provide you with a way to lower the padding or add padding in places which makes it hard to use with a bigger diagram.

Yes. current version does not have feature controlling padding. Do you have any situation that would shrink or expand padding?