Skip to content

Commit

Permalink
Fix the docstring decoration (#5885)
Browse files Browse the repository at this point in the history 
* Fix the docstring of the `Slider` class

* add changeset

* Update the JSON file generator to output a new field .styled_description to render the inline code syntax in the description field

* add changeset

* Update style_types() to deal with backticks and single asterisks

* Update the inline style converter to use regex for the curly bracket syntax as well

* Revert `style_types()` not to touch the `description` field and update the frontend code to apply styling to such formatted texts on Svelte's side

* Apply the inline styler to other `.description` field appearances

* Apply the inline styler to `.preprocessing`, `.postprocessing`, `.examples-format`, `.events`, and `*.parameters.doc`

* Stop applying HTML styles to the JSON data, instaed apply HTML escaping

* Escape HTML tokens in .parameters[]["doc"] too

* fixes

---------

Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>
Co-authored-by: Ali Abdalla <ali.si3luwa@gmail.com>
  • Loading branch information
@whitphx @gradio-pr-bot @aliabd
3 people committed Nov 28, 2023
1 parent 9bf1ad4 commit 9919b8a
Show file tree
Hide file tree
Showing 10 changed files with 110 additions and 35 deletions.
6 changes: 6 additions & 0 deletions .changeset/petite-feet-design.md
View file
@@ -0,0 +1,6 @@
---
"gradio": minor
"website": minor
---

feat:Fix the docstring decoration
2 changes: 1 addition & 1 deletion gradio/components/slider.py
View file
Expand Up @@ -17,7 +17,7 @@
@document()
class Slider(FormComponent):
"""
Creates a slider that ranges from `minimum` to `maximum` with a step size of `step`.
Creates a slider that ranges from {minimum} to {maximum} with a step size of {step}.
Preprocessing: passes slider value as a {float} into the function.
Postprocessing: expects an {int} or {float} returned from function and sets slider value to it as long as it is within range.
Examples-format: A {float} or {int} representing the slider's value.
Expand Down
32 changes: 22 additions & 10 deletions js/_website/generate_jsons/src/docs/__init__.py
View file
@@ -1,3 +1,4 @@
import html
import json
import os

Expand Down Expand Up @@ -93,9 +94,22 @@ def add_guides():
add_guides()


def style_types():
def escape_parameters(parameters):
new_parameters = []
for param in parameters:
param = param.copy() # Manipulating the list item directly causes issues, so copy it first
param["doc"] = html.escape(param["doc"]) if param["doc"] else param["doc"]
new_parameters.append(param)
assert len(new_parameters) == len(parameters)
return new_parameters


def escape_html_string_fields():
for mode in docs:
for cls in docs[mode]:
# print(cls["description"])
# cls["description"] = html.escape(cls["description"])
# print(cls["description"])
for tag in [
"preprocessing",
"postprocessing",
Expand All @@ -104,17 +118,15 @@ def style_types():
]:
if tag not in cls["tags"]:
continue
cls[tag] = (
cls["tags"][tag]
.replace(
"{",
"<span class='text-orange-500' style='font-family: monospace; font-size: large;' >",
)
.replace("}", "</span>")
)
cls["tags"][tag] = html.escape(cls["tags"][tag])

cls["parameters"] = escape_parameters(cls["parameters"])
for fn in cls["fns"]:
fn["description"] = html.escape(fn["description"])
fn["parameters"] = escape_parameters(fn["parameters"])
# 1/0

style_types()
escape_html_string_fields()


def override_signature(name, signature):
Expand Down
4 changes: 2 additions & 2 deletions js/_website/src/lib/components/EventListeners.svelte
View file
Expand Up @@ -46,7 +46,7 @@
</p>
</td>
<td class="p-3 break-words text-gray-700">
<p>{fn.description}</p>
<p>{@html fn.description}</p>
</td>
</tr>
{/each}
Expand Down Expand Up @@ -89,7 +89,7 @@
{/if}
</td>
<td class="p-3 text-gray-700 break-words">
<p>{param["doc"] || ""}</p>
<p>{@html param["doc"] || ""}</p>
</td>
</tr>
{/if}
Expand Down
2 changes: 1 addition & 1 deletion js/_website/src/lib/components/FunctionDoc.svelte
View file
Expand Up @@ -126,7 +126,7 @@
{/if}
</td>
<td class="p-3 text-gray-700 break-words">
<p>{param["doc"] || ""}</p>
<p>{@html param["doc"] || ""}</p>
</td>
</tr>
{/if}
Expand Down
16 changes: 16 additions & 0 deletions js/_website/src/lib/text.ts
View file
@@ -0,0 +1,16 @@
const regex_italic = /\*(.*?)\*/g;
const regex_code = /`(.*?)`/g;
const regex_curly_brackets = /\{(.*?)\}/g;

export function style_formatted_text(formatted_text: string): string {
return formatted_text
.replace(regex_italic, "<em class='italic font-semibold'>$1</em>")
.replace(
regex_code,
"<code class='text-orange-500' style='font-family: monospace; font-size: large;'>$1</code>"
)
.replace(
regex_curly_brackets,
"<code class='text-orange-500' style='font-family: monospace; font-size: large;'>$1</code>"
);
}
41 changes: 41 additions & 0 deletions js/_website/src/routes/[[version]]/docs/[doc]/+page.server.ts
View file
Expand Up @@ -2,6 +2,7 @@ import Prism from "prismjs";
import "prismjs/components/prism-python";
import { make_slug_processor } from "$lib/utils";
import { error } from "@sveltejs/kit";
import { style_formatted_text } from "$lib/text";

let language = "python";

Expand Down Expand Up @@ -69,6 +70,7 @@ export async function load({ params, parent }) {

if ("description" in obj) {
headers.push(["Description", "description"]);
obj.description = style_formatted_text(obj.description);
}

if ("demos" in obj) {
Expand Down Expand Up @@ -120,6 +122,45 @@ export async function load({ params, parent }) {
}
}
}
for (const fn of obj.fns) {
if ("description" in fn) {
fn.description = style_formatted_text(fn.description);
}
if (fn.parameters.length > 0) {
for (const param of fn.parameters) {
if (param.doc) {
param.doc = style_formatted_text(param.doc);
}
}
}
}
}
if ("tags" in obj) {
if ("preprocessing" in obj.tags) {
obj.tags.preprocessing = style_formatted_text(
obj.tags.preprocessing
);
}
if ("postprocessing" in obj.tags) {
obj.tags.postprocessing = style_formatted_text(
obj.tags.postprocessing
);
}
if ("examples_format" in obj.tags) {
obj.tags.examples_format = style_formatted_text(
obj.tags.examples_format
);
}
if ("events" in obj.tags) {
obj.tags.events = style_formatted_text(obj.tags.events);
}
}
if (obj.parameters.length > 0) {
for (const param of obj.parameters) {
if (param.doc) {
param.doc = style_formatted_text(param.doc);
}
}
}
}
}
Expand Down
14 changes: 7 additions & 7 deletions js/_website/src/routes/[[version]]/docs/[doc]/+page.svelte
View file
Expand Up @@ -242,24 +242,24 @@
</h4>
<p class="text-lg text-gray-500">
<span class="text-gray-700">As input: </span>
{@html obj.preprocessing}
{@html obj.tags.preprocessing}
</p>
<p class="text-lg text-gray-500">
<span class="text-gray-700">As output:</span>
{@html obj.postprocessing}
{@html obj.tags.postprocessing}
</p>
{#if obj.examples_format}
{#if obj.tags.examples_format}
<p class="text-lg text-gray-500">
<span class="text-gray-700"
>Format expected for examples:</span
>
{@html obj.examples_format}
{@html obj.tags.examples_format}
</p>
{/if}
{#if obj.events && obj.events.length > 0}
{#if obj.tags.events && obj.tags.events.length > 0}
<p class="text-lg text-gray-500">
<span class="text-gray-700">Supported events:</span>
<em>{@html obj.events}</em>
<em>{@html obj.tags.events}</em>
</p>
{/if}
</div>
Expand Down Expand Up @@ -331,7 +331,7 @@
{/if}
</td>
<td class="p-3 text-gray-700 break-words">
<p>{param["doc"] || ""}</p>
<p>{@html param["doc"] || ""}</p>
</td>
</tr>
{/if}
Expand Down
14 changes: 7 additions & 7 deletions js/_website/src/routes/[[version]]/docs/flagging/+page.svelte
View file
Expand Up @@ -236,24 +236,24 @@
{#if mode === "components"}
<p class="mb-2 text-lg text-gray-500">
<span class="text-orange-500">As input: </span>
{@html obj.preprocessing}
{@html obj.tags.preprocessing}
</p>
<p class="mb-2 text-lg text-gray-500">
<span class="text-orange-500">As output:</span>
{@html obj.postprocessing}
{@html obj.tags.postprocessing}
</p>
{#if obj.examples_format}
{#if obj.tags.examples_format}
<p class="mb-2 text-lg text-gray-500">
<span class="text-orange-500"
>Format expected for examples:</span
>
{@html obj.examples_format}}
{@html obj.tags.examples_format}
</p>
{/if}
{#if obj.events && obj.events.length > 0}
{#if obj.tags.events && obj.tags.events.length > 0}
<p class="text-lg text-gray-500">
<span class="text-orange-500">Supported events:</span>
<em>{@html obj.events}</em>
<em>{@html obj.tags.events}</em>
</p>
{/if}
{/if}
Expand Down Expand Up @@ -325,7 +325,7 @@
{/if}
</td>
<td class="p-3 text-gray-700 break-words">
<p>{param["doc"] || ""}</p>
<p>{@html param["doc"] || ""}</p>
</td>
</tr>
{/if}
Expand Down
14 changes: 7 additions & 7 deletions js/_website/src/routes/[[version]]/docs/themes/+page.svelte
View file
Expand Up @@ -242,24 +242,24 @@
{#if mode === "components"}
<p class="mb-2 text-lg text-gray-500">
<span class="text-orange-500">As input: </span>
{@html obj.preprocessing}
{@html obj.tags.preprocessing}
</p>
<p class="mb-2 text-lg text-gray-500">
<span class="text-orange-500">As output:</span>
{@html obj.postprocessing}
{@html obj.tags.postprocessing}
</p>
{#if obj.examples_format}
{#if obj.tags.examples_format}
<p class="mb-2 text-lg text-gray-500">
<span class="text-orange-500"
>Format expected for examples:</span
>
{@html obj.examples_format}}
{@html obj.tags.examples_format}
</p>
{/if}
{#if obj.events && obj.events.length > 0}
{#if obj.tags.events && obj.tags.events.length > 0}
<p class="text-lg text-gray-500">
<span class="text-orange-500">Supported events:</span>
<em>{@html obj.events}</em>
<em>{@html obj.tags.events}</em>
</p>
{/if}
{/if}
Expand Down Expand Up @@ -331,7 +331,7 @@
{/if}
</td>
<td class="p-3 text-gray-700 break-words">
<p>{param["doc"] || ""}</p>
<p>{@html param["doc"] || ""}</p>
</td>
</tr>
{/if}
Expand Down

0 comments on commit 9919b8a

Please sign in to comment.