Feature request: Markdown/HTML support for descriptions

[Vincas Dargis]

Currently, view's __doc__-string is printed escaped. Newlines does not work. That's pretty primitive, limited way of documenting view.

It would be very useful to have optional Markdwon, or even raw HTML support. Maybe it could be something like this:

@jsonrpc.method('x.a', description_format=DescriptionFormat.Text)
def index() -> str:
    """Simple text, without newlines or html entities, as currently is. DescriptionFormat.Text would be default."""
    return ""

@jsonrpc.method('x.b', description_format=DescriptionFormat.Markdown)
def index() -> str:
    """
    Some **very** `formatted` 
    > Markdown
    """
    return ""

@jsonrpc.method('x.c', description_format=DescriptionFormat.RAW)
def index() -> str:
    """<p> Some <b>RAW</b> HTML</p><br/>
    <p>Better use Markdown though as it's better human readable in code.</p>"""
    return ""

Or maybe just read hardcoded prefix like this:

@jsonrpc.method('x.a')
def index() -> str:
"""markdown: This description will be preprocessed as **Makdown**!"""

[Nycholas Oliveira]

Yes, it sounds good.

My idea here is to create a schema definition for API Browser that allows setting the what parse the API Browser will use to render the method description (summary / __doc__), based on Sphinx[1]:

browse = JSONRPCBrowe(
   extensions = ['myst_parser'],
   parser = 'markdown',
)

app = Flask('docstring')
jsonrpc_v1 = JSONRPC(app, '/api/v1', browse=browse)

Will it solve your use case?

[1] - https://www.sphinx-doc.org/en/master/usage/markdown.html

[Vincas Dargis]

Yes, I guess that could work. Making Browser extensible will help in other cases in the future too.