Implement text renderer.

[csadorf]

For rendering of markdown documents in text format.

The concrete use case is the ability to render templated markdown documents directly within a terminal environment.

[csadorf]

This patch enables a very concrete use case for signac and I would be interested in some feedback on whether there is any interest in merging this particular functionality into the package before I finalize this.

[bdice]

Since signac intends to use this in a terminal context, it might be a nice touch to use terminal bolding. I've used this in other applications with several terminals / multiple platforms, so I think it works reliably.

Suggested change

	return '**' + text + '**'
	return '\033[1m' + text + '\033[0m'

[bdice]

And maybe TerminalRenderer is a better name than TextRenderer? Not sure.

[csadorf]

I recognize that I didn't fully commit to either text or terminal rendering both in the code and the branch name. 😄

I'm happy to fix that before moving forward.

[lepture]

I'm not quite sure if it is ok to include this into mistune; how about making your own renderer a python project, because it is using bs4.

In mistune, I'd like to keep it dependency free.

[bdice]

@lepture @csadorf I see a couple paths forward, feel free to chime in if you have other ideas:

• The dependency on bs4 could be removed, with some work. If that was done, would this feature be suitable for inclusion in mistune?
• If not, and we need to create our own renderer, we could still depend on mistune for the parsing and just implement our own rendering class (essentially copy-paste this PR into our project).

[csadorf]

I'm not quite sure if it is ok to include this into mistune; how about making your own renderer a python project, because it is using bs4.

In mistune, I'd like to keep it dependency free.

@lepture The dependency on bs4 is a stop-gap solution to implement the prototype. The patch is currently a rough prototype which I would clean up before requesting the actual merge.

Despite the dependency, anything else that we we would need to change before you could accept the contribution?

[lepture]

Is there a standard for this text renderer. I'm not quite sure what is the format you are using. So if it is for terminal, I see text **strong**, but there is actually a bold style with ansi escape. If you are meaning ansi escape for terminal, I'd like to call this renderer AnsiRenderer.

It is ok to include it in mistune if it is dependency free since terminal is a common use case.

[zhou-pj]

Is there a standard for this text renderer. I'm not quite sure what is the format you are using. So if it is for terminal, I see text **strong**, but there is actually a bold style with ansi escape. If you are meaning ansi escape for terminal, I'd like to call this renderer AnsiRenderer.

It is ok to include it in mistune if it is dependency free since terminal is a common use case.

@lepture I think we can write our own function to replace bs4 used in the prototype. The tabulate package is also used here, for this one, would it be ok to just copy the tabulate.py into this package?

[zhou-pj]

@vyasr this PR should be ready to go.

[vyasr]

@zhou-pj can you mark this as ready for review?

[zhou-pj]

@vyasr I don't think we have access to do that.
@lepture We think this PR is ready for your review.

[waylan]

+1 for the AnsiRenderer. However, what is the point of the text renderer? I could see a markdown renderer which output cleaned up Markdown. However, this text renderer is incomplete. I see no support for nested list items (which should be indented). And it only supports unordered lists. Ordered lists raise an assertion error. And various methods fail to account for possible None values. Those were the immediately obvious ones from a quite glance at the code.

As an aside, I discovered this after I started work on my own markdown renderer. I am finding the renderer API very limiting for doing a proper full markdown renderer (properly numbering and incrementing ordered lists being a prime example). I would suggest that 2.0 final shouldn't be released until the renderer API supports doing a complete markdown renderer.

[csadorf]

+1 for the AnsiRenderer. However, what is the point of the text renderer? I could see a markdown renderer which output cleaned up Markdown. However, this text renderer is incomplete. I see no support for nested list items (which should be indented). And it only supports unordered lists. Ordered lists raise an assertion error. And various methods fail to account for possible None values. Those were the immediately obvious ones from a quite glance at the code.

@waylan The use case is very specifically to have a canonical formatting that specifically handles proper formatting of tables, etc. The only difference between the ansi and the text renderer is that the former uses control characters for bold formatting etc., and the latter does not. I think it would be fine to remove the text rendered if this poses a roadblock, however it is probably fair to say that neither the pure text and the ansi renderer follow a specific standard, they just produce a formatted version of the marked up input.

With respect to the limitations, you are absolutely correct, that this implementation is incomplete. I created this draft PR with the help of @zhou-pj and @vyasr to get some feedback on the approach and to gauge whether there is general interest to merge this into the code base. I unfortunately did not have any time to prioritize this lately, which is why in the end we decided to vendor a forked version of the package that works for our purposes. However, I am happy to provide assistance in moving this forward.

[csadorf]

It appears there is no interest in this.