Feedback on v0.1.0

[martinpriestley]

Hoorah! I'd just started to dabble with a ReST exporter of my own, but as ever you've done something much more comprehensive.

I see you're soliciting feedback on Reddit. Here's some thoughts after a brief play:

1. Fields

• field descriptions under a docnode / doctree haven't been given labels (or indeed headings), so we can't refer to them (except via the HTML)
• docnode can't be used on a field in isolation. Not sure if that's desirable or not, but it's not what your documentation implies.

2. RDL formatcode support

• I can see you're not a fan, but using these rather than Markdown does keep one's RDL compatible with other tools.
• In an ideal world the formatting would be translated to ReST, for Sphinx to render in any builder. However, ReST text formatting is very limited (no underlining, strikethrough, colours, and heaven forefend you should want bold AND italic), so lots of the RDLFC wouldn't map cleanly without lots of custom style jazz.
• For the HTML builder you've already done the work in SystemRDL compiler. Why not use get_html_desc() directly?
• https://github.com/SystemRDL/systemrdl-compiler/blob/e6bd222554912fdc6a183e6674a6ba5d75e07632/src/systemrdl/core/rdlformatcode.py#L10 is straightforward to rewrite to use LaTeX tags
• I don't know about epub or other builders

3. Cross references from node descriptions

• Is there a sensible way to refer to a node from another node's description, and have that render as a hyperlink?
• Similarly, is there a sensible way to refer embed :ref: to other labels in the document? (At this point the RDL descriptions might become less meaningful outside of the Sphinx doc, since the links can't work, but that could be a reasonable price to pay for some).

4. Enum descriptions in a docnode

• missing

[amykyta3]

Thanks for checking the project out and the early feedback!

• Agree that fields ought to have some mechanism for creating an anchor/reference. I had missed that. Created Improve ability to cross-reference and link to fields in docnode output #4
• Yes currently docnode intentionally does not support fields (or signals). Not sure if there would be much utility for that since usually you want the context around its placement within a register anyways. I'll clarify that in the docs. Wasn't planning on supporting field docnodes unless there is good motivation to do so.
• The reason I'm not using the existing get_html_desc() mechanism is because that only translates to HTML. Sphinx works better if I convert to the intermediate docutils format. Since the docutils intermediate representation is output-agnostic, it gives the flexibility to convert to any format like PDF, epub, etc, not just HTML. Once I work out the kinks with the new translation back-end, I will likely backport it to the compiler's get_html_desc() mechanism.
• I'm definitely planning on adding RDLFormatCode support. As implied by the above, I believe I have a better path forward with this new back-end flow that I am using that will be much more streamlined than my original implementation. I have created issue Add support for RDLFormatCode #2 to track this.
• Regarding epub and other builders, yes it should work. There may be some styling kinks I still need to work out though. Currently it will indeed generate the content, but it may not look particularly pretty yet.
• Enums: Yes aware and definitely planned. Created Add enums to docnode output #3 to track this.
• Cross references - I definitely want to enhance the RDL-side cross reference mechanism somehow. This would likely be using some additional markdown syntax extension. Still not clear how I want to do this though, but I am indeed thinking about this exact thing.

[amykyta3]

I missed your comment about LaTeX tags. Can you clarify what you mean by that?

[martinpriestley]

Hi Alex,

Sounds like you've got all the important things in hand.

Re the formatting, my point is that ReStructuredText (and I think docutils generally, though I'm less sure there) doesn't have much support for explicit text formatting. I don't see how one would implement the rdlfc [color] tag, for example. So whilst I agree it's desirable to just translate to docutils and let Sphinx do the rest for any and all formats, I think the result might be disappointing.

Another example: Markdown supports strikethrough but docutils doesn't. Here's the Myst implementation: https://github.com/executablebooks/MyST-Parser/blob/8a44f5d35197b19aab2f1fe35b6f1dce4960bce5/myst_parser/mdit_to_docutils/base.py#L1371

The RDLFC tags do mosly map trivially to HTML (as you've done in SystemRDL compiler), and have LaTeX equivalents:

RDLFC	Docutils	HTML	LaTeX
[b]	strong	<b>	\textbf{
[i]	emphasis	<i>	\textit{
[u]	NA	<u>	\underline{
[color=xx]	NA	<span style="color:%s">	\textcolor{%s}{
[size=xx]	NA	<span style="font-size:%s">	various
etc.

so it'd be straightforward to do a get_latex_desc(). Though I've just twigged that Myst isn't going to give you LaTeX, so this would only work for RDLFC and not Markdown. Sigh.

Or you could just not support the bits that docutils doesn't implement. Who's colouring their text anyway? TBH all I ever use is [list].

[amykyta3]

This is generally not an issue. Sphinx has many extensions to the docutils tree nodes beyond what the official doctree spec defines. In other cases, one can create formatting token bypasses based on the specific output renderer.

Here's the snippet of code that MyST uses to provide support for strikethroughs for HTML output: https://github.com/executablebooks/MyST-Parser/blob/8a44f5d35197b19aab2f1fe35b6f1dce4960bce5/myst_parser/mdit_to_docutils/base.py#L1371-L1382

This would be pretty easy to extend to also provide rendering for LaTeX output (for PDF) and other formats.
Similar mechanism would be used to handle other RDLFC tags like color and size.

I'm already extending this renderer class to handle some things, and was planning to build on top of it more to handle all the RDLFC tags.

[amykyta3]

Or you could just not support the bits that docutils doesn't implement. Who's colouring their text anyway? TBH all I ever use is [list].

Philosophically agree to this 100% 😆. My biggest gripe with with RDLFC is that it was haphazardly borrowed from PHPBB tags which came from the dark ages before CSS and the concept of semantic styling was popularized. Despite my opinion that size and color styling is wholly inappropriate, I'm still motivated to support it since it is still part of the RDL spec and is important for compatibility reasons as you have pointed out (even if it is technically part of an optional "informative" annex of the spec).

[martinpriestley]

Excellent. Carry on...