Bring Pyphen hyphenation to the Doxygen theme as well

[mosra]

Opening an issue to avoid forgetting about this, as I don't have time to look into it right now.

What needs to be done:

• [ ] Intercept various places where HTML code is produced and call Pyphen in there (may be quite ugly, best would be to reuse the docutils document tree but that's much much more work)
• [ ] Avoid calling Pyphen in problematic cases (inline code, code blocks, links where link title is an URL, math blocks, function parameter names, ...), try to match the behavior with the corresponding Pelican plugin (is it done for headings? or just for copy?)
• [ ] Getting the hyphenation language from Doxyfile setting (is there any way to specify language per-file or per-paragraph as in reST? I assume not)
• [ ] Ability to control the hyphenation globally (M_HYPHENATION, maybe?)
• [ ] Ability to control the hyphenation per-paragraph (some @m_hyphenate{lang|off} command, maybe?)

Cc: @jbakosi

[mosra]

Some further thoughts about this:

Currently I am converting the Doxygen XML-encoded detailed descriptions straight to HTML code, which is kinda fine for the m.css HTML5 theme, but quite awful for anybody that would want to heavily modify the theme (or do any processing of the parsed stuff). This also makes it impossible to reuse the work I did on various Pelican plugins (plots, graphs, math, ...) -- every time I basically need to write the frontend code twice, test it twice etc.

One option could be to convert the XML to reST sources and then reuse existing docutils parsers and writers that I already have for Pelican. This is almost what Breathe does -- it converts the XML to a source that can be read by Sphinx. To me that seems like a lot of unnecessary extra work, hitting many of the limitations of reST (such as inability to nest inline elements, add classes to links, ...) and adding another layer where syntax errors and assertions might occur (there's enough of that in the XML parsing already).

Another option (preferred) would be to create the docutils node tree directly and then just using my existing HTML5 writer I did for Pelican to produce the output. Maybe this could be even shared with the Breathe/Sphinx project in the end. (Is Sphinx able to consume docutils node tree directly?)

Besides hyphenation, this would also allow the following features:

• smart quotes and other typographic goodies
• spell checking
• well, basically any filter that can be applied on the resulting node tree
• other output formats than just HTML5 (docutils has native latex output, for example)
• embedding arbitrary reST markup in case markdown or doxygen syntax is not enough
• reusing any existing reST directives and plugins "just like that" without needing to rewrite them for this tool

[jbakosi]

Without understanding all the above, it sounds like you know what you are doing and that this is going be a lot more and better than just adding hyphenation to the doxygen theme. ;-)