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

docs: Use definition lists for parameter descriptions to enable full markdown support be #901

Merged
merged 10 commits into from
Dec 18, 2023
1 change: 1 addition & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@ _inv/
_sidebar.yml
/.quarto/
objects.json
site_libs/
2 changes: 1 addition & 1 deletion docs/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/_quarto.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ project:
format:
html:
toc: true
css: shiny-docs.css

website:
title: "Shiny for Python (dev version)"
Expand Down
2 changes: 2 additions & 0 deletions docs/_quartodoc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -46,6 +47,7 @@ quartodoc:
contents:
- ui.sidebar
- ui.layout_sidebar
- ui.layout_columns
- ui.layout_column_wrap
- ui.card
- ui.card_header
Expand Down
14 changes: 11 additions & 3 deletions docs/_renderer.py
Original file line number Diff line number Diff line change
Expand Up @@ -158,15 +158,14 @@ def render(self, el: ds.DocstringParameter):
# Wrap everything in a code block to allow for links
param = "<code>" + param + "</code>"

clean_desc = sanitize(el.description, allow_markdown=True)
return (param, clean_desc)
return (param, el.description)

@dispatch
def render(self, el: ds.DocstringSectionParameters):
rows = list(map(self.render, el.value))
header = ["Parameter", "Description"]

return self._render_table(rows, header)
return render_definition_list(rows)

@dispatch
def signature(self, el: dc.Function, source: Optional[dc.Alias] = None):
Expand All @@ -184,6 +183,15 @@ 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)


gadenbuie marked this conversation as resolved.
Show resolved Hide resolved
def html_escape_except_backticks(s: str) -> str:
"""
HTML-escape a string, except for content inside of backticks.
Expand Down
4 changes: 4 additions & 0 deletions docs/shiny-docs.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
#parameters dd {
margin-top: 0.5rem;
margin-left: 2rem;
}
52 changes: 31 additions & 21 deletions shiny/express/layout.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
-------
Expand Down Expand Up @@ -168,21 +173,26 @@ 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
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
Expand Down
58 changes: 32 additions & 26 deletions shiny/ui/_include_helpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down Expand Up @@ -105,19 +108,22 @@ 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.
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
Expand Down
27 changes: 16 additions & 11 deletions shiny/ui/_layout.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,21 +43,26 @@ 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
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
Expand Down
40 changes: 24 additions & 16 deletions shiny/ui/_sidebar.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
-------
Expand Down Expand Up @@ -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.

Expand Down
24 changes: 14 additions & 10 deletions shiny/ui/_valuebox.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading