Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature request: Markdown/HTML support for descriptions #374

Open
Talkless opened this issue Mar 9, 2023 · 2 comments
Open

Feature request: Markdown/HTML support for descriptions #374

Talkless opened this issue Mar 9, 2023 · 2 comments
Assignees

Comments

@Talkless
Copy link
Contributor

Talkless commented Mar 9, 2023

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**!"""
@Talkless Talkless changed the title Featire request: Markdown/HTML support for descriptions Feature request: Markdown/HTML support for descriptions Mar 16, 2023
@nycholas nycholas self-assigned this Mar 20, 2023
@nycholas
Copy link
Member

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

@Talkless
Copy link
Contributor Author

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

nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 25, 2023
The expected behavior is that when using the modular way, the API
Browser merges in one, instead of having one API Browser for each.

Now, the server is aware of the `SERVER_NAME` Flask configuration,
it is being used by API Browser to request the correct server,
besides that, the API Browser is able to call servers in different
domains. For that configuration, the `JSONRPCSite` generates the
`path` and `base_url` variables from `SERVER_NAME`, `APPLICATION_ROOT`,
and `PREFERRED_URL_SCHEME`.

It is the first step to providing a Browse Schema to improve
documentation and examples from API (JSON-RPC methods).

Resolves: #388
See: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 27, 2023
It's very important to provide a safe way to change
the Web Browsable API in the next tasks.

See also: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 27, 2023
It's very important to provide a safe way to change
the Web Browsable API in the next tasks.

See also: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 27, 2023
It's very important to provide a safe way to change
the Web Browsable API in the next tasks.

See also: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 27, 2023
It's very important to provide a safe way to change
the Web Browsable API in the next tasks.

See also: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 29, 2023
It's very important to provide a safe way to change
the Web Browsable API in the next tasks.

See also: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 29, 2023
It's very important to provide a safe way to change
the Web Browsable API in the next tasks.

See also: #378, #377, #376, #374, #373, and #370
nycholas added a commit that referenced this issue Mar 29, 2023
It's very important to provide a safe way to change
the Web Browsable API in the next tasks.

See also: #378, #377, #376, #374, #373, and #370
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants