From 9ffd6fc6dc3a9d21a06bd0d751ac8deb5d015bc4 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 19 Dec 2023 09:59:07 -0500 Subject: [PATCH 1/7] Update _quarto.yml --- docs/_quarto.yml | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 4250b1efc..5aaac6051 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -40,9 +40,19 @@ website: format: html: theme: cosmo - # css: styles.css + css: styles.css toc: true +filters: + - interlinks + +interlinks: + sources: + numpy: + url: https://numpy.org/doc/stable/ + python: + url: https://docs.python.org/3/ + # tell quarto to read the generated sidebar metadata-files: - _sidebar.yml @@ -51,6 +61,7 @@ quartodoc: package: great_tables sidebar: _sidebar.yml dynamic: true + render_interlinks: true sections: - title: Table Creation desc: > From b52446154b2b92ed5e74afce1d2f513054fdee52 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 19 Dec 2023 09:59:13 -0500 Subject: [PATCH 2/7] Create styles.css --- docs/styles.css | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/styles.css diff --git a/docs/styles.css b/docs/styles.css new file mode 100644 index 000000000..cf6f0be5a --- /dev/null +++ b/docs/styles.css @@ -0,0 +1,47 @@ +.table a { + text-underline-offset: 4px; + font-family: ui-monospace; + color: steelblue; + font-weight: bold; + font-size: 0.875em; +} + +.sidebar-item-container { + text-transform: uppercase; + font-weight: bold; +} + +.depth1 { + font-family: ui-monospace; +} + +p,h1,h2,h3 { + font-family: Inter, Roboto, "Helvetica Neue", "Arial Nova", "Nimbus Sans", Arial, sans-serif; +} + +code { + font-family: ui-monospace; + font-size: 0.875em; + color: rgb(18, 18, 18); +} + +h1,h2,h3,#toc-title,#toc-function-reference,.nav-link { + font-family: "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; +} + +#quarto-sidebar > div > ul > li:nth-child(1) > div > a > span { + text-transform: uppercase; + font-weight: bold; +} + +.navbar-title { + font-family: Inter, Roboto, "Helvetica Neue", "Arial Nova", "Nimbus Sans", Arial, sans-serif; + font-weight: bold; + animation: color-change 5s infinite !important; +} + +@keyframes color-change { + 0% { color: #7e4fdf; } + 50% { color: #df4c00; } + 100% { color: #7e4fdf; } +} From fc07b69aab00ed596769a9b6343ae5206e5b57a6 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 19 Dec 2023 09:59:28 -0500 Subject: [PATCH 3/7] Update _formats.py --- great_tables/_formats.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/great_tables/_formats.py b/great_tables/_formats.py index f8323e8ee..eb54d34a2 100644 --- a/great_tables/_formats.py +++ b/great_tables/_formats.py @@ -223,7 +223,7 @@ def fmt_number( See Also -------- - The `fmt_integer()` method might be more useful if you really need to format numeric values to + The [`fmt_integer()`](`great_tables.GT.fmt_integer`) method might be more useful if you really need to format numeric values to appear as integers (i.e., no decimals will be shown and input values are rounded as necessary). Need to do numeric formatting on a value or list of values? Take a look at the functional version of this method: `val_fmt_number()`. From 04c0aa72dbfb85e077ca55c061dbd18e6e424fb6 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 19 Dec 2023 10:00:01 -0500 Subject: [PATCH 4/7] Add Interlinks Quarto extension --- docs/_extensions/machow/interlinks/.gitignore | 3 + .../machow/interlinks/_extension.yml | 7 + .../machow/interlinks/interlinks.lua | 254 ++++++++++++++++++ 3 files changed, 264 insertions(+) create mode 100644 docs/_extensions/machow/interlinks/.gitignore create mode 100644 docs/_extensions/machow/interlinks/_extension.yml create mode 100644 docs/_extensions/machow/interlinks/interlinks.lua diff --git a/docs/_extensions/machow/interlinks/.gitignore b/docs/_extensions/machow/interlinks/.gitignore new file mode 100644 index 000000000..5a1bf0b4e --- /dev/null +++ b/docs/_extensions/machow/interlinks/.gitignore @@ -0,0 +1,3 @@ +*.html +*.pdf +*_files/ diff --git a/docs/_extensions/machow/interlinks/_extension.yml b/docs/_extensions/machow/interlinks/_extension.yml new file mode 100644 index 000000000..c8a812136 --- /dev/null +++ b/docs/_extensions/machow/interlinks/_extension.yml @@ -0,0 +1,7 @@ +title: Interlinks +author: Michael Chow +version: 1.1.0 +quarto-required: ">=1.2.0" +contributes: + filters: + - interlinks.lua diff --git a/docs/_extensions/machow/interlinks/interlinks.lua b/docs/_extensions/machow/interlinks/interlinks.lua new file mode 100644 index 000000000..47aa61fa6 --- /dev/null +++ b/docs/_extensions/machow/interlinks/interlinks.lua @@ -0,0 +1,254 @@ +local function read_inv_text(filename) + -- read file + local file = io.open(filename, "r") + if file == nil then + return nil + end + local str = file:read("a") + file:close() + + + local project = str:match("# Project: (%S+)") + local version = str:match("# Version: (%S+)") + + local data = {project = project, version = version, items = {}} + + local ptn_data = + "^" .. + "(.-)%s+" .. -- name + "([%S:]-):" .. -- domain + "([%S]+)%s+" .. -- role + "(%-?%d+)%s+" .. -- priority + "(%S*)%s+" .. -- uri + "(.-)\r?$" -- dispname + + + -- Iterate through each line in the file content + for line in str:gmatch("[^\r\n]+") do + if not line:match("^#") then + -- Match each line against the pattern + local name, domain, role, priority, uri, dispName = line:match(ptn_data) + + -- if name is nil, raise an error + if name == nil then + error("Error parsing line: " .. line) + end + + data.items[#data.items + 1] = { + name = name, + domain = domain, + role = role, + priority = priority, + uri = uri, + dispName = dispName + } + end + end + return data +end + +local function read_json(filename) + + local file = io.open(filename, "r") + if file == nil then + return nil + end + local str = file:read("a") + file:close() + + local decoded = quarto.json.decode(str) + return decoded +end + +local function read_inv_text_or_json(base_name) + local file = io.open(base_name .. ".txt", "r") + if file then + -- TODO: refactors so we don't just close the file immediately + io.close(file) + json = read_inv_text(base_name .. ".txt") + + else + json = read_json(base_name .. ".json") + end + + return json +end + +local inventory = {} + +local function lookup(search_object) + + local results = {} + for _, inv in ipairs(inventory) do + for _, item in ipairs(inv.items) do + -- e.g. :external+:::`` + if item.inv_name and item.inv_name ~= search_object.inv_name then + goto continue + end + + if item.name ~= search_object.name then + goto continue + end + + if search_object.role and item.role ~= search_object.role then + goto continue + end + + if search_object.domain and item.domain ~= search_object.domain then + goto continue + else + if search_object.domain or item.domain == "py" then + table.insert(results, item) + end + + goto continue + end + + ::continue:: + end + end + + if #results == 1 then + return results[1] + end + if #results > 1 then + quarto.log.warning("Found multiple matches for " .. search_object.name .. ", using the first match.") + return results[1] + end + if #results == 0 then + quarto.log.warning("Found no matches for object:\n", search_object) + end + + return nil +end + +local function mysplit (inputstr, sep) + if sep == nil then + sep = "%s" + end + local t={} + for str in string.gmatch(inputstr, "([^"..sep.."]+)") do + table.insert(t, str) + end + return t +end + +local function normalize_role(role) + if role == "func" then + return "function" + end + return role +end + +local function build_search_object(str) + local starts_with_colon = str:sub(1, 1) == ":" + local search = {} + if starts_with_colon then + local t = mysplit(str, ":") + if #t == 2 then + -- e.g. :py:func:`my_func` + search.role = normalize_role(t[1]) + search.name = t[2]:match("%%60(.*)%%60") + elseif #t == 3 then + -- e.g. :py:func:`my_func` + search.domain = t[1] + search.role = normalize_role(t[2]) + search.name = t[3]:match("%%60(.*)%%60") + elseif #t == 4 then + -- e.g. :ext+inv:py:func:`my_func` + search.external = true + + search.inv_name = t[1]:match("external%+(.*)") + search.domain = t[2] + search.role = normalize_role(t[3]) + search.name = t[4]:match("%%60(.*)%%60") + else + quarto.log.warning("couldn't parse this link: " .. str) + return {} + end + else + search.name = str:match("%%60(.*)%%60") + end + + if search.name == nil then + quarto.log.warning("couldn't parse this link: " .. str) + return {} + end + + if search.name:sub(1, 1) == "~" then + search.shortened = true + search.name = search.name:sub(2, -1) + end + return search +end + +local function report_broken_link(link, search_object, replacement) + -- TODO: how to unescape html elements like [? + return pandoc.Code(pandoc.utils.stringify(link.content)) +end + +function Link(link) + -- do not process regular links ---- + if not link.target:match("%%60") then + return link + end + + -- lookup item ---- + local search = build_search_object(link.target) + local item = lookup(search) + + -- determine replacement, used if no link text specified ---- + local original_text = pandoc.utils.stringify(link.content) + local replacement = search.name + if search.shortened then + local t = mysplit(search.name, ".") + replacement = t[#t] + end + + -- set link text ---- + if original_text == "" and replacement ~= nil then + link.content = pandoc.Code(replacement) + end + + -- report broken links ---- + if item == nil then + return report_broken_link(link, search) + end + link.target = item.uri:gsub("%$$", search.name) + + + return link +end + +local function fixup_json(json, prefix) + for _, item in ipairs(json.items) do + item.uri = prefix .. item.uri + end + table.insert(inventory, json) +end + +return { + { + Meta = function(meta) + local json + local prefix + if meta.interlinks and meta.interlinks.sources then + for k, v in pairs(meta.interlinks.sources) do + local base_name = quarto.project.offset .. "/_inv/" .. k .. "_objects" + json = read_inv_text_or_json(base_name) + prefix = pandoc.utils.stringify(v.url) + if json ~= nil then + fixup_json(json, prefix) + end + end + end + json = read_inv_text_or_json(quarto.project.offset .. "/objects") + if json ~= nil then + fixup_json(json, "/") + end + end + }, + { + Link = Link + } +} From 5e47835cc4d50ef85fad3551cc4fedbbec13ad26 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 19 Dec 2023 12:58:07 -0500 Subject: [PATCH 5/7] Update _quarto.yml --- docs/_quarto.yml | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 5aaac6051..462ac6336 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -53,6 +53,8 @@ interlinks: python: url: https://docs.python.org/3/ +html-table-processing: none + # tell quarto to read the generated sidebar metadata-files: - _sidebar.yml @@ -65,9 +67,9 @@ quartodoc: sections: - title: Table Creation desc: > - All tables created in **Great Tables** begin by using `GT()`. Here we supply the input - data table and some basic options for creating a stub (`rowname_col`) and row groups - (`groupname_col`). + All tables created in **Great Tables** begin by using [`GT()`](`great_tables.GT`). With this + class, we supply the input data table and some basic options for creating a stub and row + groups (with the `rowname_col` and `groupname_col` arguments). contents: - GT - title: Creating or modifying parts of a table @@ -75,8 +77,8 @@ quartodoc: A table can contain a few useful components for conveying additional information. These include a header (with a titles and subtitle), a footer (with footnotes and source notes), and additional areas for labels (row group labels, column spanner labels, the stubhead - label). We can modify the look of table parts more generally with `tab_options()` and - perform styling on targeted table locations with `tab_style()`. + label). We can perform styling on targeted table locations with the + [`tab_style()`](`great_tables.GT.tab_style`) method. contents: - GT.tab_header - GT.tab_spanner @@ -88,7 +90,7 @@ quartodoc: Columns of data can be formatted with the `fmt_*()` methods. We can specify the rows of these columns quite precisely with the `rows` argument. We get to apply these methods exactly once to each data cell (last call wins). Need to do custom formatting? Use the - `fmt()` method and define your own formatter within. + [`fmt()`](`great_tables.GT.fmt`) method and define your own formatter. contents: - GT.fmt_number - GT.fmt_integer @@ -104,8 +106,9 @@ quartodoc: - title: Modifying columns desc: > The `cols_*()` methods allow for modifications that act on entire columns. This includes - alignment of the data in columns (`cols_align()`), hiding columns from view (`cols_hide()`), - re-labeling the column labels (`cols_label()`), and moving columns around (the + alignment of the data in columns ([`cols_align()`](`great_tables.GT.cols_align`)), hiding + columns from view ([`cols_hide()`](`great_tables.GT.cols_hide`)), re-labeling the column + labels ([`cols_label()`](`great_tables.GT.cols_label`)), and moving columns around (with the `cols_move*()` methods). contents: - GT.cols_align @@ -117,9 +120,9 @@ quartodoc: - title: Location Targeting and Styling Classes desc: > Location targeting is a powerful feature of **Great Tables**. It allows for the precise - selection of table locations for styling (using the `tab_style()` method). The styling - classes allow for the specification of the styling properties to be applied to the targeted - locations. + selection of table locations for styling (using the + [`tab_style()`](`great_tables.GT.tab_style`) method). The styling classes allow for the + specification of the styling properties to be applied to the targeted locations. contents: - loc.body - style.fill @@ -127,10 +130,12 @@ quartodoc: - style.borders - title: Helper functions desc: > - An assortment of helper functions is available in the **Great Tables** package. The `md()` - and `html()` helpers can used be during label creation with the `tab_header()`, - `tab_footnote()`, `tab_spanner()`, `tab_stubhead_label()`, and `tab_source_note()` - methods. + An assortment of helper functions is available in the **Great Tables** package. The + [`md()`](`great_tables.md`) and [`html()`](`great_tables.html`) helper functions can used + during label creation with the [`tab_header()`](`great_tables.GT.tab_header`), + [`tab_spanner()`](`great_tables.GT.tab_spanner`), + [`tab_stubhead()`](`great_tables.GT.tab_stubhead`), and + [`tab_source_note()`](`great_tables.GT.tab_source_note`) methods. contents: - md - html From 6d8bc6f03cc7606439414804d98ce049755da2f3 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 19 Dec 2023 12:58:12 -0500 Subject: [PATCH 6/7] Update styles.css --- docs/styles.css | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/styles.css b/docs/styles.css index cf6f0be5a..f32253f38 100644 --- a/docs/styles.css +++ b/docs/styles.css @@ -4,6 +4,7 @@ color: steelblue; font-weight: bold; font-size: 0.875em; + word-break: initial; } .sidebar-item-container { @@ -15,17 +16,13 @@ font-family: ui-monospace; } -p,h1,h2,h3 { - font-family: Inter, Roboto, "Helvetica Neue", "Arial Nova", "Nimbus Sans", Arial, sans-serif; -} - code { font-family: ui-monospace; font-size: 0.875em; color: rgb(18, 18, 18); } -h1,h2,h3,#toc-title,#toc-function-reference,.nav-link { +p, h1,h2,h3,#toc-title,#toc-function-reference,.nav-link,#parameters > table > tbody > tr > td { font-family: "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; } From 6d3c606ac036c6c9c3e7a64722d2189dc9bd244a Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 19 Dec 2023 12:58:28 -0500 Subject: [PATCH 7/7] Add interlinks throughout the docs --- great_tables/_boxhead.py | 11 ++-- great_tables/_formats.py | 96 +++++++++++++++++++---------------- great_tables/_formats_vals.py | 9 ++-- great_tables/_heading.py | 29 +++++------ great_tables/_helpers.py | 9 ++-- great_tables/_source_notes.py | 5 +- great_tables/_spanners.py | 18 +++---- great_tables/_stubhead.py | 11 ++-- 8 files changed, 98 insertions(+), 90 deletions(-) diff --git a/great_tables/_boxhead.py b/great_tables/_boxhead.py index 457c2b43f..7a47752eb 100644 --- a/great_tables/_boxhead.py +++ b/great_tables/_boxhead.py @@ -15,11 +15,12 @@ def cols_label(self: GTSelf, **kwargs: Any) -> GTSelf: Relabel one or more columns. Column labels can be modified from their default values (the names of the columns from the - input table data). When you create a table object using `gt.GT()`, column names effectively - become the column labels. While this serves as a good first approximation, column names - aren't often appealing as column labels in an output table. The `cols_label()` method - provides the flexibility to relabel one or more columns and we even have the option to use - the `md()` or `html()` helpers for rendering column labels from Markdown or using HTML. + input table data). When you create a table object using [`GT()`](`great_tables.GT`), column + names effectively become the column labels. While this serves as a good first approximation, + column names aren't often appealing as column labels in an output table. The `cols_label()` + method provides the flexibility to relabel one or more columns and we even have the option to + use the [`md()`](`great_tables.md`) or [`html()`](`great_tables.html`) helpers for rendering + column labels from Markdown or using HTML. It's important to note that while columns can be freely relabeled, we continue to refer to columns by their names for targeting purposes. Column names in the input data table must be diff --git a/great_tables/_formats.py b/great_tables/_formats.py index eb54d34a2..07677192a 100644 --- a/great_tables/_formats.py +++ b/great_tables/_formats.py @@ -145,7 +145,7 @@ def fmt_number( as `2.34` can, for example, be formatted with `0` decimal places and it would result in `"2"`. With `4` decimal places, the formatted value becomes `"2.3400"`. The trailing zeros can be removed with `drop_trailing_zeros=True`. If you always need `decimals = 0`, the - `fmt_integer()` method should be considered. + [`fmt_integer()`](`great_tables.GT.fmt_integer`) method should be considered. n_sigfig : Optional[int] A option to format numbers to *n* significant figures. By default, this is `None` and thus number values will be formatted according to the number of decimal places set via @@ -206,8 +206,8 @@ def fmt_number( preferred values. Note that a `locale` value provided here will override any global locale setting performed in - `GT()`'s own `locale` argument (it is settable there as a value received by all other methods - that have a `locale` argument). + [`GT()`](`great_tables.GT`)'s own `locale` argument (it is settable there as a value received by + all other methods that have a `locale` argument). Examples -------- @@ -223,10 +223,11 @@ def fmt_number( See Also -------- - The [`fmt_integer()`](`great_tables.GT.fmt_integer`) method might be more useful if you really need to format numeric values to - appear as integers (i.e., no decimals will be shown and input values are rounded as necessary). - Need to do numeric formatting on a value or list of values? Take a look at the functional - version of this method: `val_fmt_number()`. + The [`fmt_integer()`](`great_tables.GT.fmt_integer`) method might be more useful if you really + need to format numeric values to appear as integers (i.e., no decimals will be shown and input + values are rounded as necessary). Need to do numeric formatting on a value or list of values? + Take a look at the functional version of this method: + [`val_fmt_number()`](`great_tables._formats_vals.val_fmt_number`). """ # Stop if `locale` does not have a valid value; normalize locale and resolve one @@ -378,8 +379,8 @@ def fmt_integer( provided in `sep_mark`, it will be overridden by the locale's preferred value. Note that a `locale` value provided here will override any global locale setting performed in - `GT()`'s own `locale` argument (it is settable there as a value received by all other methods - that have a `locale` argument). + [`GT()`](`great_tables.GT`)'s own `locale` argument (it is settable there as a value received by + all other methods that have a `locale` argument). Examples -------- @@ -395,9 +396,10 @@ def fmt_integer( See Also -------- - The `fmt_number()` method might be more of what you need if you'd like decimal values in your - outputs. Need to do integer-based formatting on a value or list of values? Take a look at the - functional version of this method: `val_fmt_integer()`. + The [`fmt_number()`](`great_tables.GT.fmt_number`) method might be more of what you need if + you'd like decimal values in your outputs. Need to do integer-based formatting on a value or + list of values? Take a look at the functional version of this method: + [`val_fmt_integer()`](`great_tables._formats_vals.val_fmt_integer`). """ # Stop if `locale` does not have a valid value; normalize locale and resolve one @@ -514,8 +516,7 @@ def fmt_scientific( The `decimals` values corresponds to the exact number of decimal places to use. A value such as `2.34` can, for example, be formatted with `0` decimal places and it would result in `"2"`. With `4` decimal places, the formatted value becomes `"2.3400"`. The trailing zeros - can be removed with `drop_trailing_zeros=True`. If you always need `decimals = 0`, the - `fmt_integer()` method should be considered. + can be removed with `drop_trailing_zeros=True`. n_sigfig : Optional[int] A option to format numbers to *n* significant figures. By default, this is `None` and thus number values will be formatted according to the number of decimal places set via @@ -578,8 +579,8 @@ def fmt_scientific( preferred values. Note that a `locale` value provided here will override any global locale setting performed in - `GT()`'s own `locale` argument (it is settable there as a value received by all other methods - that have a `locale` argument). + [`GT()`](`great_tables.GT`)'s own `locale` argument (it is settable there as a value received by + all other methods that have a `locale` argument). Examples -------- @@ -595,8 +596,9 @@ def fmt_scientific( See Also -------- - The functional version of this method, `val_fmt_scientific()`, allows you to format a single - numerical value (or a list of them). + The functional version of this method, + [`val_fmt_scientific()`](`great_tables._formats_vals.val_fmt_scientific`), allows you to format + a single numerical value (or a list of them). """ # Set a default value for `use_seps`; these separators are only used for very @@ -772,8 +774,7 @@ def fmt_percent( The `decimals` values corresponds to the exact number of decimal places to use. A value such as `2.34` can, for example, be formatted with `0` decimal places and it would result in `"2"`. With `4` decimal places, the formatted value becomes `"2.3400"`. The trailing zeros - can be removed with `drop_trailing_zeros=True`. If you always need `decimals = 0`, the - `fmt_integer()` method should be considered. + can be removed with `drop_trailing_zeros=True`. drop_trailing_zeros : bool A boolean value that allows for removal of trailing zeros (those redundant zeros after the decimal mark). @@ -831,13 +832,14 @@ def fmt_percent( preferred values. Note that a `locale` value provided here will override any global locale setting performed in - `GT()`'s own `locale` argument (it is settable there as a value received by all other methods - that have a `locale` argument). + [`GT()`](`great_tables.GT`)'s own `locale` argument (it is settable there as a value received by + all other methods that have a `locale` argument). See Also -------- - The functional version of this method, `val_fmt_percent()`, allows you to format a single - numerical value (or a list of them). + The functional version of this method, + [`val_fmt_percent()`](`great_tables._formats_vals.val_fmt_percent`), allows you to format a + single numerical value (or a list of them). """ # Stop if `locale` does not have a valid value; normalize locale and resolve one @@ -1036,8 +1038,8 @@ def fmt_currency( a `currency` allows **Great Tables** to obtain the currency code from the locale's territory. Note that a `locale` value provided here will override any global locale setting performed in - `GT()`'s own `locale` argument (it is settable there as a value received by all other methods - that have a `locale` argument). + [`GT()`](`great_tables.GT`)'s own `locale` argument (it is settable there as a value received by + all other methods that have a `locale` argument). Examples -------- @@ -1052,8 +1054,9 @@ def fmt_currency( See Also -------- - The functional version of this method, `val_fmt_currency()`, allows you to format a single - numerical value (or a list of them). + The functional version of this method, + [`val_fmt_currency()`](`great_tables._formats_vals.val_fmt_currency`), allows you to format a + single numerical value (or a list of them). """ # Stop if `locale` does not have a valid value; normalize locale and resolve one @@ -1194,8 +1197,8 @@ def fmt_roman( Examples -------- Let's first create a DataFrame containing small numeric values and then introduce that to - `GT()`. We'll then format the `roman` column to appear as Roman numerals with the `fmt_roman()` - method. + [`GT()`](`great_tables.GT`). We'll then format the `roman` column to appear as Roman numerals + with the `fmt_roman()` method. ```{python} import pandas as pd @@ -1208,7 +1211,8 @@ def fmt_roman( See Also -------- - The functional version of this method, `val_fmt_roman()`, allows you to format a single + The functional version of this method, + [`val_fmt_roman()`](`great_tables._formats_vals.val_fmt_roman`), allows you to format a single numerical value (or a list of them). """ @@ -1366,8 +1370,8 @@ def fmt_bytes( preferred values. Note that a `locale` value provided here will override any global locale setting performed in - `GT()`'s own `locale` argument (it is settable there as a value received by all other methods - that have a `locale` argument). + [`GT()`](`great_tables.GT`)'s own `locale` argument (it is settable there as a value received by + all other methods that have a `locale` argument). Examples -------- @@ -1383,7 +1387,8 @@ def fmt_bytes( See Also -------- - The functional version of this method, `val_fmt_bytes()`, allows you to format a single + The functional version of this method, + [`val_fmt_bytes()`](`great_tables._formats_vals.val_fmt_bytes`), allows you to format a single numerical value (or a list of them). """ @@ -1567,9 +1572,9 @@ def fmt_date( -------------------------------------- This formatting method can adapt outputs according to a provided `locale` value. Examples include `"en"` for English (United States) and `"fr"` for French (France). Note that a `locale` - value provided here will override any global locale setting performed in `GT()`'s own `locale` - argument (it is settable there as a value received by all other methods that have a `locale` - argument). + value provided here will override any global locale setting performed in + [`GT()`](`great_tables.GT`)'s own `locale` argument (it is settable there as a value received by + all other methods that have a `locale` argument). Examples -------- @@ -1587,7 +1592,8 @@ def fmt_date( See Also -------- - The functional version of this method, `val_fmt_date()`, allows you to format a single + The functional version of this method, + [`val_fmt_date()`](`great_tables._formats_vals.val_fmt_date`), allows you to format a single numerical value (or a list of them). """ @@ -1698,9 +1704,9 @@ def fmt_time( -------------------------------------- This formatting method can adapt outputs according to a provided `locale` value. Examples include `"en"` for English (United States) and `"fr"` for French (France). Note that a `locale` - value provided here will override any global locale setting performed in `GT()`'s own `locale` - argument (it is settable there as a value received by all other methods that have a `locale` - argument). + value provided here will override any global locale setting performed in + [`GT()`](`great_tables.GT`)'s own `locale` argument (it is settable there as a value received by + all other methods that have a `locale` argument). Examples -------- @@ -1718,7 +1724,8 @@ def fmt_time( See Also -------- - The functional version of this method, `val_fmt_time()`, allows you to format a single + The functional version of this method, + [`val_fmt_time()`](`great_tables._formats_vals.val_fmt_time`), allows you to format a single numerical value (or a list of them). """ @@ -1799,8 +1806,9 @@ def fmt_markdown( See Also -------- - The functional version of this method, `val_fmt_markdown()`, allows you to format a single - string value (or a list of them). + The functional version of this method, + [`val_fmt_markdown()`](`great_tables._formats_vals.val_fmt_markdown`), allows you to format a + single string value (or a list of them). """ # Generate a function that will operate on single `x` values in the table body diff --git a/great_tables/_formats_vals.py b/great_tables/_formats_vals.py index ebae4c4ad..cb3bd44ca 100644 --- a/great_tables/_formats_vals.py +++ b/great_tables/_formats_vals.py @@ -70,7 +70,8 @@ def val_fmt_number( as `2.34` can, for example, be formatted with `0` decimal places and it would result in `"2"`. With `4` decimal places, the formatted value becomes `"2.3400"`. The trailing zeros can be removed with `drop_trailing_zeros=True`. If you always need `decimals = 0`, the - `fmt_integer()` method should be considered. + [`val_fmt_integer()`](`great_tables._formats_vals.val_fmt_integer`) function should be + considered. n_sigfig : Optional[int] A option to format numbers to *n* significant figures. By default, this is `None` and thus number values will be formatted according to the number of decimal places set via @@ -274,8 +275,7 @@ def val_fmt_scientific( The `decimals` values corresponds to the exact number of decimal places to use. A value such as `2.34` can, for example, be formatted with `0` decimal places and it would result in `"2"`. With `4` decimal places, the formatted value becomes `"2.3400"`. The trailing zeros - can be removed with `drop_trailing_zeros=True`. If you always need `decimals = 0`, the - `fmt_integer()` method should be considered. + can be removed with `drop_trailing_zeros=True`. n_sigfig : Optional[int] A option to format numbers to *n* significant figures. By default, this is `None` and thus number values will be formatted according to the number of decimal places set via @@ -397,8 +397,7 @@ def val_fmt_percent( The `decimals` values corresponds to the exact number of decimal places to use. A value such as `2.34` can, for example, be formatted with `0` decimal places and it would result in `"2"`. With `4` decimal places, the formatted value becomes `"2.3400"`. The trailing zeros - can be removed with `drop_trailing_zeros=True`. If you always need `decimals = 0`, the - `fmt_integer()` method should be considered. + can be removed with `drop_trailing_zeros=True`. drop_trailing_zeros : bool A boolean value that allows for removal of trailing zeros (those redundant zeros after the decimal mark). diff --git a/great_tables/_heading.py b/great_tables/_heading.py index 12808783c..20b3a31d5 100644 --- a/great_tables/_heading.py +++ b/great_tables/_heading.py @@ -1,12 +1,7 @@ from __future__ import annotations from typing import TYPE_CHECKING, Optional, Union, List -from typing_extensions import Self - from ._gt_data import Heading -from copy import copy - - if TYPE_CHECKING: from ._types import GTSelf @@ -23,16 +18,19 @@ def tab_header( We can add a table header to the output table that contains a title and even a subtitle with the `tab_header()` method. A table header is an optional table component that is positioned above the column labels. We have the flexibility to use Markdown or HTML formatting for the header's - title and subtitle with the `md()` and `html()` helper functions. + title and subtitle with the [`md()`](`great_tables.md`) and [`html()`](`great_tables.html`) + helper functions. Parameters ---------- title : str - Text to be used in the table title. We can elect to use the `md()` and `html()` helper - functions to style the text as Markdown or to retain HTML elements in the text. + Text to be used in the table title. We can elect to use the [`md()`](`great_tables.md`) and + [`html()`](`great_tables.html`) helper functions to style the text as Markdown or to retain + HTML elements in the text. subtitle : str - Text to be used in the table subtitle. We can elect to use the `md()` and `html()` - helper functions to style the text as Markdown or to retain HTML elements in the text. + Text to be used in the table subtitle. We can elect to use the [`md()`](`great_tables.md`) + and [`html()`](`great_tables.html`) helper functions to style the text as Markdown or to + retain HTML elements in the text. preheader (str) Optional preheader content that is rendered above the table. Can be supplied as a list of strings. @@ -44,10 +42,10 @@ def tab_header( Examples -------- - Let's use a small portion of the `gtcars` dataset to create a table. A header part can be - added to the table with the `tab_header()` method. We'll add a title and the optional - subtitle as well. With the `md()` helper function, we can make sure the Markdown formatting - is interpreted and transformed. + Let's use a small portion of the `gtcars` dataset to create a table. A header part can be added + to the table with the `tab_header()` method. We'll add a title and the optional subtitle as + well. With the [`md()`](`great_tables.md`) helper function, we can make sure the Markdown + formatting is interpreted and transformed. ```{python} import great_tables as gt @@ -63,7 +61,8 @@ def tab_header( ) ``` - We can alternatively use the `html()` helper function to retain HTML elements in the text. + We can alternatively use the [`html()`](`great_tables.html`) helper function to retain HTML + elements in the text. ```{python} ( diff --git a/great_tables/_helpers.py b/great_tables/_helpers.py index f49ed277b..55a53bcf6 100644 --- a/great_tables/_helpers.py +++ b/great_tables/_helpers.py @@ -59,10 +59,9 @@ def pct(x: Union[int, float]) -> str: def md(text: str) -> Text: """Interpret input text as Markdown-formatted text. - Markdown! It's a wonderful thing. We can use it in certain places (e.g., footnotes, source - notes, the table title, etc.) and expect it to render to HTML as Markdown does. There is the - `html()` helper that allows you to ferry in HTML but this function `md()`... it's almost like a - two-for-one deal (you get to use Markdown plus any HTML fragments at the same time). + Markdown can be used in certain places (e.g., source notes, table title/subtitle, etc.) and we + can expect it to render to HTML. There is also the [`html()`](`great_tables.html`) helper + function that allows you to use raw HTML text. Parameters ---------- @@ -83,7 +82,7 @@ def html(text: str) -> Text: For certain pieces of text (like in column labels or table headings) we may want to express them as raw HTML. In fact, with HTML, anything goes so it can be much more than just text. The `html()` function will guard the input HTML against escaping, so, your HTML tags will come - through as HTML when rendered... to HTML. + through as HTML when rendered. Parameters ---------- diff --git a/great_tables/_source_notes.py b/great_tables/_source_notes.py index 9c8d4b5bd..3053dd506 100644 --- a/great_tables/_source_notes.py +++ b/great_tables/_source_notes.py @@ -20,8 +20,9 @@ def tab_source_note(data: GTSelf, source_note: str) -> GTSelf: Parameters ---------- source_note : str - Text to be used in the source note. We can optionally use the `md()` or `html()` helpers - to style the text as Markdown or to retain HTML elements in the text. + Text to be used in the source note. We can optionally use the [`md()`](`great_tables.md`) or + [`html()`](`great_tables.html`) helper functions to style the text as Markdown or to retain + HTML elements in the text. Returns ------- diff --git a/great_tables/_spanners.py b/great_tables/_spanners.py index 9a0fe858a..3f1de4040 100644 --- a/great_tables/_spanners.py +++ b/great_tables/_spanners.py @@ -42,8 +42,9 @@ def tab_spanner( Parameters ---------- label : str - The text to use for the spanner label. We can optionally use the [md()] and [html()] helpers - to style the text as Markdown or to retain HTML elements in the text. + The text to use for the spanner label. We can optionally use the [`md()`](`great_tables.md`) + and [`html()`](`great_tables.html`) helper functions to style the text as Markdown or to + retain HTML elements in the text. columns : Union[str, List[str], None] The columns to target. Can either be a single column name or a series of column names provided in a list. @@ -58,13 +59,12 @@ def tab_spanner( is `0`. id : Optional[str] The ID for the spanner. When accessing a spanner through the `spanners` argument of - `tab_spanner()` or `cells_column_spanners()` (when using `tab_style()` or `tab_footnote()`) - the `id` value is used as the reference (and not the `label`). If an `id` is not explicitly - provided here, it will be taken from the `label` value. It is advisable to set an explicit - `id` value if you plan to access this cell in a later call and the label text is complicated - (e.g., contains markup, is lengthy, or both). Finally, when providing an `id` value you must - ensure that it is unique across all ID values set for spanner labels (the method will throw - an error if `id` isn't unique). + `tab_spanner()` the `id` value is used as the reference (and not the `label`). If an `id` + is not explicitly provided here, it will be taken from the `label` value. It is advisable to + set an explicit `id` value if you plan to access this cell in a later call and the label + text is complicated (e.g., contains markup, is lengthy, or both). Finally, when providing + an `id` value you must ensure that it is unique across all ID values set for spanner labels + (the method will throw an error if `id` isn't unique). gather : bool An option to move the specified `columns` such that they are unified under the spanner. Ordering of the moved-into-place columns will be preserved in all cases. By default, this diff --git a/great_tables/_stubhead.py b/great_tables/_stubhead.py index 4ef9d8982..f9a8b67cd 100644 --- a/great_tables/_stubhead.py +++ b/great_tables/_stubhead.py @@ -16,15 +16,16 @@ def tab_stubhead(self: GTSelf, label: Union[str, Text]) -> GTSelf: Add a label to the stubhead of a table. The stubhead is the lone element that is positioned left of the column labels, and above the stub. If a stub does not exist, then there is no stubhead (so no change will be made when using this method in that case). We have the - flexibility to use Markdown formatting for the stubhead label (through use of the `md()` - helper function). Furthermore, we can use HTML for the stubhead label so long as we also use - the `html()` helper function. + flexibility to use Markdown formatting for the stubhead label (through use of the + [`md()`](`great_tables.md`) helper function). Furthermore, we can use HTML for the stubhead + label so long as we also use the [`html()`](`great_tables.html`) helper function. Parameters ---------- label : str - The text to be used as the stubhead label. We can optionally use the `md()` and `html()` - functions to style the text as Markdown or to retain HTML elements in the text. + The text to be used as the stubhead label. We can optionally use the + [`md()`](`great_tables.md`) and [`html()`](`great_tables.html`) helper functions to style + the text as Markdown or to retain HTML elements in the text. Returns -------