From b229fcc3f9c49f49c837ecac1cec946d44855942 Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Tue, 12 Dec 2023 16:23:49 -0500 Subject: [PATCH 1/9] feat(docs): Customize quartodoc parameter rendering to use grid tables This allows markdown in the parameter documentation to be rendered correctly. --- docs/_renderer.py | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/_renderer.py b/docs/_renderer.py index 7020ec69b..2e822a6ec 100644 --- a/docs/_renderer.py +++ b/docs/_renderer.py @@ -14,6 +14,7 @@ from plum import dispatch from quartodoc import MdRenderer from quartodoc.renderers.base import convert_rst_link_to_md, sanitize +from tabulate import tabulate SHINY_PATH = Path(files("shiny").joinpath()) @@ -158,7 +159,7 @@ def render(self, el: ds.DocstringParameter): # Wrap everything in a code block to allow for links param = "" + param + "" - clean_desc = sanitize(el.description, allow_markdown=True) + clean_desc = el.description.replace("|", "|") return (param, clean_desc) @dispatch @@ -166,7 +167,7 @@ def render(self, el: ds.DocstringSectionParameters): rows = list(map(self.render, el.value)) header = ["Parameter", "Description"] - return self._render_table(rows, header) + return render_grid_table(rows, header) @dispatch def signature(self, el: dc.Function, source: Optional[dc.Alias] = None): @@ -184,6 +185,16 @@ def signature(self, el: dc.Function, source: Optional[dc.Alias] = None): return super().signature(el, source) +def render_grid_table(rows: list[tuple[str, str]], headers: list[str]) -> str: + table = tabulate(rows, headers=headers, tablefmt="grid") + + # TODO: pandoc (via quarto) adds an empty row for certain tables. We should + # find the offending characters and fix them, but for now this works. + table = table + "\n\n" + + return table + + def html_escape_except_backticks(s: str) -> str: """ HTML-escape a string, except for content inside of backticks. From d88854c2405264096d248857114f25903a5313a6 Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Tue, 12 Dec 2023 16:24:07 -0500 Subject: [PATCH 2/9] docs: Add `layout_columns()` to the reference index --- docs/_quartodoc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_quartodoc.yml b/docs/_quartodoc.yml index 5e70da411..7f05f48f6 100644 --- a/docs/_quartodoc.yml +++ b/docs/_quartodoc.yml @@ -18,6 +18,7 @@ quartodoc: - express.layout.span - express.layout.pre - express.layout.sidebar + - express.layout.layout_columns - express.layout.layout_column_wrap - express.layout.column - express.layout.row @@ -46,6 +47,7 @@ quartodoc: contents: - ui.sidebar - ui.layout_sidebar + - ui.layout_columns - ui.layout_column_wrap - ui.card - ui.card_header From 94e25308650b9f67af2c9d7a778066459e4a8240 Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Tue, 12 Dec 2023 16:24:27 -0500 Subject: [PATCH 3/9] docs: `make quartodoc` depends on `PYBIN` and `VENV` --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 026aa511f..91fabe65c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -46,7 +46,7 @@ deps: $(PYBIN) ## Install build dependencies $(PYBIN)/pip install pip --upgrade $(PYBIN)/pip install -e ..[doc] -quartodoc: ## Build qmd files for API docs +quartodoc: $(PYBIN) ## Build qmd files for API docs . $(PYBIN)/activate \ && quartodoc interlinks \ && quartodoc build --config _quartodoc.yml --verbose From 05f9ed92d2b3d6f446d55e349913041b86718ec9 Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Tue, 12 Dec 2023 16:27:41 -0500 Subject: [PATCH 4/9] docs(layout_column_wrap): Update `width` parameter docs --- shiny/express/layout.py | 16 +++++++++------- shiny/ui/_layout.py | 16 +++++++++------- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/shiny/express/layout.py b/shiny/express/layout.py index 2a88f1c50..88096ceb0 100644 --- a/shiny/express/layout.py +++ b/shiny/express/layout.py @@ -168,13 +168,15 @@ def layout_column_wrap( Parameters ---------- width - The desired width of each card. It can be a (unit-less) number between 0 and 1 - and should be specified as `1/num`, where `num` represents the number of desired - columns. It can be a CSS length unit representing either the minimum (when - `fixed_width=False`) or fixed width (`fixed_width=True`). It can also be `None`, - which allows power users to set the `grid-template-columns` CSS property - manually, either via a `style` attribute or a CSS stylesheet. If missing, a - value of `200px` will be used. + The desired width of each card. It can be one of the following: + + * A (unit-less) number between 0 and 1, specified as `1/num`, where `num` + represents the number of desired columns. + * A CSS length unit representing either the minimum (when `fixed_width=False`) + or fixed width (`fixed_width=True`). + * `None`, which allows power users to set the `grid-template-columns` CSS + property manually, either via a `style` attribute or a CSS stylesheet. + * If missing, a value of `200px` will be used. fixed_width When `width` is greater than 1 or is a CSS length unit, e.g. `"200px"`, `fixed_width` indicates whether that `width` value represents the absolute size diff --git a/shiny/ui/_layout.py b/shiny/ui/_layout.py index 8f59af2a1..ffcb52420 100644 --- a/shiny/ui/_layout.py +++ b/shiny/ui/_layout.py @@ -43,13 +43,15 @@ def layout_column_wrap( :func:`~shiny.ui.card`). Named arguments become attributes on the containing :class:`~htmltools.Tag` element. width - The desired width of each card. It can be a (unit-less) number between 0 and 1 - and should be specified as `1/num`, where `num` represents the number of desired - columns. It can be a CSS length unit representing either the minimum (when - `fixed_width=False`) or fixed width (`fixed_width=True`). It can also be `None`, - which allows power users to set the `grid-template-columns` CSS property - manually, either via a `style` attribute or a CSS stylesheet. If missing, a - value of `200px` will be used. + The desired width of each card. It can be one of the following: + + * A (unit-less) number between 0 and 1, specified as `1/num`, where `num` + represents the number of desired columns. + * A CSS length unit representing either the minimum (when `fixed_width=False`) + or fixed width (`fixed_width=True`). + * `None`, which allows power users to set the `grid-template-columns` CSS + property manually, either via a `style` attribute or a CSS stylesheet. + * If missing, a value of `200px` will be used. fixed_width When `width` is greater than 1 or is a CSS length unit, e.g. `"200px"`, `fixed_width` indicates whether that `width` value represents the absolute size From 7219c3ccbfba6c8075a9b81198f5da14a89e6675 Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Tue, 12 Dec 2023 16:30:32 -0500 Subject: [PATCH 5/9] docs: git ignore `docs/site_libs/` folder --- docs/.gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.gitignore b/docs/.gitignore index 95eb9c701..a3135790a 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -4,3 +4,4 @@ _inv/ _sidebar.yml /.quarto/ objects.json +site_libs/ From 0aee2f7d0bb7d53ca790914cea857c569b3980bb Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Wed, 13 Dec 2023 09:55:03 -0500 Subject: [PATCH 6/9] docs: Use definition lists for parameters instead of a table --- docs/_quarto.yml | 1 + docs/_renderer.py | 13 ++++++------- docs/shiny-docs.css | 4 ++++ 3 files changed, 11 insertions(+), 7 deletions(-) create mode 100644 docs/shiny-docs.css diff --git a/docs/_quarto.yml b/docs/_quarto.yml index b4f5d299c..3e1093ae7 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -5,6 +5,7 @@ project: format: html: toc: true + css: shiny-docs.css website: title: "Shiny for Python (dev version)" diff --git a/docs/_renderer.py b/docs/_renderer.py index 2e822a6ec..81aeadc9e 100644 --- a/docs/_renderer.py +++ b/docs/_renderer.py @@ -167,7 +167,7 @@ def render(self, el: ds.DocstringSectionParameters): rows = list(map(self.render, el.value)) header = ["Parameter", "Description"] - return render_grid_table(rows, header) + return render_definition_list(rows) @dispatch def signature(self, el: dc.Function, source: Optional[dc.Alias] = None): @@ -185,14 +185,13 @@ def signature(self, el: dc.Function, source: Optional[dc.Alias] = None): return super().signature(el, source) -def render_grid_table(rows: list[tuple[str, str]], headers: list[str]) -> str: - table = tabulate(rows, headers=headers, tablefmt="grid") +def render_definition_list(rows: list[tuple[str, str]]) -> str: + def indent_newlines(s: str) -> str: + return s.replace("\n", "\n ") - # TODO: pandoc (via quarto) adds an empty row for certain tables. We should - # find the offending characters and fix them, but for now this works. - table = table + "\n\n" + out = [f"{param}\n\n: {indent_newlines(desc)}" for param, desc in rows] - return table + return "\n\n".join(out) def html_escape_except_backticks(s: str) -> str: diff --git a/docs/shiny-docs.css b/docs/shiny-docs.css new file mode 100644 index 000000000..f5b1c0ba3 --- /dev/null +++ b/docs/shiny-docs.css @@ -0,0 +1,4 @@ +#parameters dd { + margin-top: 0.5rem; + margin-left: 2rem; +} From 848aadc56942878e5ba68b24196d75ab6f836b78 Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Wed, 13 Dec 2023 10:38:09 -0500 Subject: [PATCH 7/9] docs: Reformat some long parameter descriptions --- shiny/express/layout.py | 36 +++++++++++++--------- shiny/ui/_include_helpers.py | 59 ++++++++++++++++++++---------------- shiny/ui/_layout.py | 11 ++++--- shiny/ui/_sidebar.py | 40 ++++++++++++++---------- shiny/ui/_valuebox.py | 24 +++++++++------ 5 files changed, 100 insertions(+), 70 deletions(-) diff --git a/shiny/express/layout.py b/shiny/express/layout.py index 88096ceb0..19b6f659d 100644 --- a/shiny/express/layout.py +++ b/shiny/express/layout.py @@ -82,10 +82,12 @@ def sidebar( position Where the sidebar should appear relative to the main content. open - The initial state of the sidebar. It can be `"desktop"` (the sidebar starts open - on desktop screen, closed on mobile), `"open"` or `True` (the sidebar starts - open), `"closed"` or `False` (the sidebar starts closed), or `"always"` or - `None` (the sidebar is always open and cannot be closed). + The initial state of the sidebar. + + * `"desktop"`: the sidebar starts open on desktop screen, closed on mobile + * `"open"` or `True`: the sidebar starts open + * `"closed"` or `False`: the sidebar starts closed + * `"always"` or `None`: the sidebar is always open and cannot be closed In :func:`~shiny.ui.update_sidebar`, `open` indicates the desired state of the sidebar. Note that :func:`~shiny.ui.update_sidebar` can only open or close the @@ -114,12 +116,15 @@ def sidebar( padding Padding within the sidebar itself. This can be a numeric vector (which will be interpreted as pixels) or a character vector with valid CSS lengths. `padding` - may be one to four values. If one, then that value will be used for all four - sides. If two, then the first value will be used for the top and bottom, while - the second value will be used for left and right. If three, then the first will - be used for top, the second will be left and right, and the third will be - bottom. If four, then the values will be interpreted as top, right, bottom, and - left respectively. + may be one to four values. + + * If a single value, then that value will be used for all four sides. + * If two, then the first value will be used for the top and bottom, while + the second value will be used for left and right. + * If three values, then the first will be used for top, the second will be left + and right, and the third will be bottom. + * If four, then the values will be interpreted as top, right, bottom, and left + respectively. Returns ------- @@ -181,10 +186,13 @@ def layout_column_wrap( When `width` is greater than 1 or is a CSS length unit, e.g. `"200px"`, `fixed_width` indicates whether that `width` value represents the absolute size of each column (`fixed_width=TRUE`) or the minimum size of a column - (`fixed_width=FALSE`). When `fixed_width=FALSE`, new columns are added to a row - when `width` space is available and columns will never exceed the container or - viewport size. When `fixed_width=TRUE`, all columns will be exactly `width` - wide, which may result in columns overflowing the parent container. + (`fixed_width=FALSE`). + + When `fixed_width=FALSE`, new columns are added to a row when `width` space is + available and columns will never exceed the container or viewport size. + + When `fixed_width=TRUE`, all columns will be exactly `width` wide, which may + result in columns overflowing the parent container. heights_equal If `"all"` (the default), every card in every row of the grid will have the same height. If `"row"`, then every card in _each_ row of the grid will have the same diff --git a/shiny/ui/_include_helpers.py b/shiny/ui/_include_helpers.py index 1739bfc40..e6a0ec7df 100644 --- a/shiny/ui/_include_helpers.py +++ b/shiny/ui/_include_helpers.py @@ -34,19 +34,22 @@ def include_js( path A path to a JS file. method - One of the following: ``"link"``, ``"link_files"``, or ``"inline"``. ``"link"`` - is the link to the CSS file via a :func:`~ui.tags.link` tag. This method is - generally preferrable to ``"inline"`` since it allows the browser to cache the - file. ``"link_files"`` is the same as ``"link"``, but also allow for the CSS - file to request other files within ``path``'s immediate parent directory (e.g., - ``@import()`` another file). Note that this isn't the default behavior because - you should **be careful not to include files in the same directory as ``path`` - that contain sensitive information**. A good general rule of thumb to follow is - to have ``path`` be located in a subdirectory of the app directory. For example, - if the app's source is located at ``/app/app.py``, then ``path`` should be - somewhere like ``/app/css/custom.css`` (and all the other relevant accompanying - 'safe' files should be located under ``/app/css/``). And finally, ``"inline"`` - is the inline the CSS file contents within a :func:`~ui.tags.style` tag. + One of the following: + + * ``"link"`` is the link to the CSS file via a :func:`~ui.tags.link` tag. This + method is generally preferable to ``"inline"`` since it allows the browser to + cache the file. + * ``"link_files"`` is the same as ``"link"``, but also allow for the CSS file to + request other files within ``path``'s immediate parent directory (e.g., + ``@import()`` another file). Note that this isn't the default behavior because + you should **be careful not to include files in the same directory as ``path`` + that contain sensitive information**. A good general rule of thumb to follow + is to have ``path`` be located in a subdirectory of the app directory. For + example, if the app's source is located at ``/app/app.py``, then ``path`` + should be somewhere like ``/app/css/custom.css`` (and all the other relevant + accompanying 'safe' files should be located under ``/app/css/``). + * ``"inline"`` is the inline the CSS file contents within a + :func:`~ui.tags.style` tag. **kwargs Attributes which are passed on to `~ui.tags.script` @@ -105,19 +108,23 @@ def include_css( path A path to a CSS file. method - One of the following: ``"link"``, ``"link_files"``, or ``"inline"``. ``"link"`` - is the link to the CSS file via a :func:`~ui.tags.link` tag. This method is - generally preferrable to ``"inline"`` since it allows the browser to cache the - file. ``"link_files"`` is the same as ``"link"``, but also allow for the CSS - file to request other files within ``path``'s immediate parent directory (e.g., - ``@import()`` another file). Note that this isn't the default behavior because - you should **be careful not to include files in the same directory as ``path`` - that contain sensitive information**. A good general rule of thumb to follow is - to have ``path`` be located in a subdirectory of the app directory. For example, - if the app's source is located at ``/app/app.py``, then ``path`` should be - somewhere like ``/app/css/custom.css`` (and all the other relevant accompanying - 'safe' files should be located under ``/app/css/``). And finally, ``"inline"`` - is the inline the CSS file contents within a :func:`~ui.tags.style` tag. + method + One of the following: + + * ``"link"`` is the link to the CSS file via a :func:`~ui.tags.link` tag. This + method is generally preferable to ``"inline"`` since it allows the browser to + cache the file. + * ``"link_files"`` is the same as ``"link"``, but also allow for the CSS file to + request other files within ``path``'s immediate parent directory (e.g., + ``@import()`` another file). Note that this isn't the default behavior because + you should **be careful not to include files in the same directory as ``path`` + that contain sensitive information**. A good general rule of thumb to follow + is to have ``path`` be located in a subdirectory of the app directory. For + example, if the app's source is located at ``/app/app.py``, then ``path`` + should be somewhere like ``/app/css/custom.css`` (and all the other relevant + accompanying 'safe' files should be located under ``/app/css/``). + * ``"inline"`` is the inline the CSS file contents within a + :func:`~ui.tags.style` tag. Returns diff --git a/shiny/ui/_layout.py b/shiny/ui/_layout.py index ffcb52420..06741f828 100644 --- a/shiny/ui/_layout.py +++ b/shiny/ui/_layout.py @@ -56,10 +56,13 @@ def layout_column_wrap( When `width` is greater than 1 or is a CSS length unit, e.g. `"200px"`, `fixed_width` indicates whether that `width` value represents the absolute size of each column (`fixed_width=TRUE`) or the minimum size of a column - (`fixed_width=FALSE`). When `fixed_width=FALSE`, new columns are added to a row - when `width` space is available and columns will never exceed the container or - viewport size. When `fixed_width=TRUE`, all columns will be exactly `width` - wide, which may result in columns overflowing the parent container. + (`fixed_width=FALSE`). + + When `fixed_width=FALSE`, new columns are added to a row when `width` space is + available and columns will never exceed the container or viewport size. + + When `fixed_width=TRUE`, all columns will be exactly `width` wide, which may + result in columns overflowing the parent container. heights_equal If `"all"` (the default), every card in every row of the grid will have the same height. If `"row"`, then every card in _each_ row of the grid will have the same diff --git a/shiny/ui/_sidebar.py b/shiny/ui/_sidebar.py index f5a7bd1b2..4f2af4e5d 100644 --- a/shiny/ui/_sidebar.py +++ b/shiny/ui/_sidebar.py @@ -168,10 +168,12 @@ def sidebar( position Where the sidebar should appear relative to the main content. open - The initial state of the sidebar. It can be `"desktop"` (the sidebar starts open - on desktop screen, closed on mobile), `"open"` or `True` (the sidebar starts - open), `"closed"` or `False` (the sidebar starts closed), or `"always"` or - `None` (the sidebar is always open and cannot be closed). + The initial state of the sidebar. + + * `"desktop"`: the sidebar starts open on desktop screen, closed on mobile + * `"open"` or `True`: the sidebar starts open + * `"closed"` or `False`: the sidebar starts closed + * `"always"` or `None`: the sidebar is always open and cannot be closed In :func:`~shiny.ui.update_sidebar`, `open` indicates the desired state of the sidebar. Note that :func:`~shiny.ui.update_sidebar` can only open or close the @@ -200,12 +202,15 @@ def sidebar( padding Padding within the sidebar itself. This can be a numeric vector (which will be interpreted as pixels) or a character vector with valid CSS lengths. `padding` - may be one to four values. If one, then that value will be used for all four - sides. If two, then the first value will be used for the top and bottom, while - the second value will be used for left and right. If three, then the first will - be used for top, the second will be left and right, and the third will be - bottom. If four, then the values will be interpreted as top, right, bottom, and - left respectively. + may be one to four values. + + * If a single value, then that value will be used for all four sides. + * If two, then the first value will be used for the top and bottom, while + the second value will be used for left and right. + * If three values, then the first will be used for top, the second will be left + and right, and the third will be bottom. + * If four, then the values will be interpreted as top, right, bottom, and left + respectively. Returns ------- @@ -337,12 +342,15 @@ def layout_sidebar( padding Padding within the sidebar itself. This can be a numeric vector (which will be interpreted as pixels) or a character vector with valid CSS lengths. `padding` - may be one to four values. If one, then that value will be used for all four - sides. If two, then the first value will be used for the top and bottom, while - the second value will be used for left and right. If three, then the first will - be used for top, the second will be left and right, and the third will be - bottom. If four, then the values will be interpreted as top, right, bottom, and - left respectively. + may be one to four values. + + * If a single value, then that value will be used for all four sides. + * If two, then the first value will be used for the top and bottom, while + the second value will be used for left and right. + * If three values, then the first will be used for top, the second will be left + and right, and the third will be bottom. + * If four, then the values will be interpreted as top, right, bottom, and left + respectively. height Any valid CSS unit to use for the height. diff --git a/shiny/ui/_valuebox.py b/shiny/ui/_valuebox.py index cdace35f1..ed9738768 100644 --- a/shiny/ui/_valuebox.py +++ b/shiny/ui/_valuebox.py @@ -337,16 +337,20 @@ def value_box( theme The name of a theme (e.g. `"primary"`, `"danger"`, `"purple"`, `"bg-green"`, `"text-red"`) for the value box, or a theme constructed with - :func:`~shiny.ui.value_box_theme`. The theme names provide a convenient way to - use your app's Bootstrap theme colors as the foreground or background colors of - the value box. For more control, you can create your own theme with - :func:`~shiny.ui.value_box_theme` where you can pass foreground and background - colors directly. Bootstrap supported color themes: `"blue"`, `"purple"`, - `"pink"`, `"red"`, `"orange"`, `"yellow"`, `"green"`, `"teal"`, and `"cyan"`. - These colors can be used with `bg-NAME`, `text-NAME`, and - `bg-gradient-NAME1-NAME2` to change the background, foreground, or use a - background gradient respectively. If a `theme` string does not start with - `text-` or `bg-`, it will be auto prefixed with `bg-`. + :func:`~shiny.ui.value_box_theme`. + + The theme names provide a convenient way to use your app's Bootstrap theme + colors as the foreground or background colors of the value box. For more + control, you can create your own theme with :func:`~shiny.ui.value_box_theme` + where you can pass foreground and background colors directly. + + Bootstrap supported color themes: `"blue"`, `"purple"`, `"pink"`, `"red"`, + `"orange"`, `"yellow"`, `"green"`, `"teal"`, and `"cyan"`. These colors can be + used with `bg-NAME`, `text-NAME`, and `bg-gradient-NAME1-NAME2` to change the + background, foreground, or use a background gradient respectively. + + If a `theme` string does not start with `text-` or `bg-`, it will be auto + prefixed with `bg-`. full_screen If `True`, an icon will appear when hovering over the card body. Clicking the icon expands the card to fit viewport size. From fc4aa67822294214a172c4fe5dddf5adc5e71f9c Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Wed, 13 Dec 2023 17:11:15 -0500 Subject: [PATCH 8/9] chore: Minor clean ups --- docs/_renderer.py | 4 +--- shiny/ui/_include_helpers.py | 1 - 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/_renderer.py b/docs/_renderer.py index 81aeadc9e..a9775fbbc 100644 --- a/docs/_renderer.py +++ b/docs/_renderer.py @@ -14,7 +14,6 @@ from plum import dispatch from quartodoc import MdRenderer from quartodoc.renderers.base import convert_rst_link_to_md, sanitize -from tabulate import tabulate SHINY_PATH = Path(files("shiny").joinpath()) @@ -159,8 +158,7 @@ def render(self, el: ds.DocstringParameter): # Wrap everything in a code block to allow for links param = "" + param + "" - clean_desc = el.description.replace("|", "|") - return (param, clean_desc) + return (param, el.description) @dispatch def render(self, el: ds.DocstringSectionParameters): diff --git a/shiny/ui/_include_helpers.py b/shiny/ui/_include_helpers.py index e6a0ec7df..88c339bb5 100644 --- a/shiny/ui/_include_helpers.py +++ b/shiny/ui/_include_helpers.py @@ -107,7 +107,6 @@ def include_css( ---------- path A path to a CSS file. - method method One of the following: From 250f328c7d651fdf4591a939f613ccf3e9dca78c Mon Sep 17 00:00:00 2001 From: Garrick Aden-Buie Date: Mon, 18 Dec 2023 09:45:28 -0500 Subject: [PATCH 9/9] chore: Upgrade to quartodoc 0.7.2 and use pandoc.blocks.DefinitionList to write parameters --- docs/_renderer.py | 22 +++++++--------------- setup.cfg | 4 ++-- 2 files changed, 9 insertions(+), 17 deletions(-) diff --git a/docs/_renderer.py b/docs/_renderer.py index a9775fbbc..fc4ccac56 100644 --- a/docs/_renderer.py +++ b/docs/_renderer.py @@ -13,6 +13,7 @@ from griffe.docstrings import dataclasses as ds from plum import dispatch from quartodoc import MdRenderer +from quartodoc.pandoc.blocks import DefinitionList from quartodoc.renderers.base import convert_rst_link_to_md, sanitize SHINY_PATH = Path(files("shiny").joinpath()) @@ -128,17 +129,17 @@ def render_annotation(self, el: None): return "" @dispatch - def render_annotation(self, el: exp.Expression): - # an expression is essentially a list[exp.Name | str] + def render_annotation(self, el: exp.Expr): + # an expression is essentially a list[exp.ExprName | str] # e.g. Optional[TagList] # -> [Name(source="Optional", ...), "[", Name(...), "]"] return "".join(map(self.render_annotation, el)) @dispatch - def render_annotation(self, el: exp.Name): + def render_annotation(self, el: exp.ExprName): # e.g. Name(source="Optional", full="typing.Optional") - return f"[{el.source}](`{el.full}`)" + return f"[{el.name}](`{el.canonical_path}`)" @dispatch def summarize(self, el: dc.Object | dc.Alias): @@ -163,9 +164,9 @@ def render(self, el: ds.DocstringParameter): @dispatch def render(self, el: ds.DocstringSectionParameters): rows = list(map(self.render, el.value)) - header = ["Parameter", "Description"] + # rows is a list of tuples of (, ) - return render_definition_list(rows) + return str(DefinitionList(rows)) @dispatch def signature(self, el: dc.Function, source: Optional[dc.Alias] = None): @@ -183,15 +184,6 @@ def signature(self, el: dc.Function, source: Optional[dc.Alias] = None): return super().signature(el, source) -def render_definition_list(rows: list[tuple[str, str]]) -> str: - def indent_newlines(s: str) -> str: - return s.replace("\n", "\n ") - - out = [f"{param}\n\n: {indent_newlines(desc)}" for param, desc in rows] - - return "\n\n".join(out) - - def html_escape_except_backticks(s: str) -> str: """ HTML-escape a string, except for content inside of backticks. diff --git a/setup.cfg b/setup.cfg index 814ccd013..15d1112a3 100644 --- a/setup.cfg +++ b/setup.cfg @@ -103,8 +103,8 @@ doc = tabulate shinylive==0.1.1 pydantic==1.10 - quartodoc==0.4.1 - griffe==0.32.3 + quartodoc==0.7.2 + griffe==0.33.0 [options.packages.find] include = shiny, shiny.*