Add tables to examples with PST styling (#571)

Author: jarrodmillman

assets/theme-css/pst/content/_tables.scss

@@ -0,0 +1,53 @@
+/**
+ * Tables
+ */
+
+// ensure table will fit in the article width and make them y-scrollable
+table {
+  display: table;
+  overflow: auto;
+
+  // default to table-center
+  margin-left: auto;
+  margin-right: auto;
+
+  &.table-right {
+    margin-right: 0;
+  }
+
+  &.table-left {
+    margin-left: 0;
+  }
+}
+
+// customize table caption from bootstrap
+// to display them on top and centered
+table caption {
+  text-align: center;
+  caption-side: top;
+  color: var(--pst-color-text-muted);
+}
+
+// MyST Markdown tables use these classes to control alignment
+th,
+td {
+  &.text-align\:left {
+    text-align: left;
+  }
+
+  &.text-align\:right {
+    text-align: right;
+  }
+
+  &.text-align\:center {
+    text-align: center;
+  }
+}
+
+// override bootstrap table colors
+.table {
+  --bs-table-bg: transparent; //background
+  --bs-table-color: var(
+    --pst-color-text-base
+  ); // ensure text and bullets are visible
+}

assets/theme-css/pst/pydata-sphinx-theme.scss

@@ -58,7 +58,7 @@
 @import "./content/lists";
 @import "./content/quotes";
 //@import "./content/spans";
-//@import "./content/tables";
+@import "./content/tables";
 @import "./content/toctree";
 //@import "./content/math";
 

doc/content/examples/kitchen-sink/tables.md

@@ -0,0 +1,57 @@
+---
+title: Tables
+---
+
+## Markdown Tables
+
+The theme supports [GFM table markdown](https://github.github.com/gfm/#tables-extension-).
+
+| Syntax    | Description |
+| --------- | ----------- |
+| Header    | Title       |
+| Paragraph | Text        |
+
+Markdown tables can be aligned:
+
+| Syntax    | Description |   Test Text |
+| :-------- | :---------: | ----------: |
+| Header    |    Title    | Here's this |
+| Paragraph |    Text     |    And more |
+
+## Table shortcode
+
+This is a feature preview and is not ready for adoption:
+
+{{< yamlToTable >}}
+headers:
+
+- Project
+- Available Packages
+- Download location
+
+format:
+
+- align: left
+- align: left
+- align: right
+
+rows:
+
+- columns:
+
+  - "NumPy"
+  - |
+    Official _source code_ (all platforms) and _binaries_ for<br/>
+    **Windows**, **Linux**, and **Mac OS X**
+  - "[PyPi page for NumPy](https://pypi.python.org/pypi/numpy)"
+
+- columns:
+  - SciPy
+  - |
+    Official _source code_ (all platforms) and _binaries_ for<br/>
+    **Windows**, **Linux** and **Mac OS X**
+  - |
+    [SciPy release page](https://github.com/scipy/scipy/releases) (sources)<br/>
+    [PyPI page for SciPy](https://pypi.python.org/pypi/scipy) (all)
+
+{{< /yamlToTable >}}

layouts/shortcodes/yamlToTable.html

@@ -1,6 +1,8 @@
 {{/*
 
 {{< yamlToTable >}}
+caption: 'Table caption'
+
 headers:
   - Project
   - Available Packages
@@ -34,9 +36,13 @@
 
 {{ $arg := .Get 0 }}
 {{ $data := .Inner | transform.Unmarshal }}
+{{- $id := printf "id%03d" $.Ordinal -}}
 
 {{ with $data }}
-<table>
+<table class="table" id="{{ $id }}">
+  {{- with .caption -}}
+  <caption><span class="caption-text">{{ . }}</span><a class="headerlink" href="#{{ $id  }}" title="Link to this table">#</a></caption>
+  {{- end }}
   {{ range .format }}
   <col
     {{ range $key, $val := . }}
@@ -46,7 +52,7 @@
   {{ end }}
 
   {{ range .headers }}
-  <th>{{ . | markdownify }}</th>
+  <th class="head">{{ . | markdownify }}</th>
   {{ end }}
 
   {{ range $row := .rows }}