Skip to content

Commit

Permalink
👌 IMPROVE: Table rendering (#450)
Browse files Browse the repository at this point in the history 
Change cell alignment classes to `text-left`, `text-center`, or `text-right`,
and allow tables with no body.
  • Loading branch information
@chrisjsewell
chrisjsewell authored Dec 4, 2021
1 parent 8da63ad commit 4c8aebe
Show file tree
Hide file tree
Showing 10 changed files with 109 additions and 39 deletions.
44 changes: 44 additions & 0 deletions docs/syntax/syntax.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -577,6 +577,50 @@ leave the "text" section of the markdown link empty. For example, this
markdown: `[](syntax.md)` will result in: [](syntax.md).
```

## Tables

Tables can be written using the standard [Github Flavoured Markdown syntax](https://github.github.com/gfm/#tables-extension-):

```md
| foo | bar |
| --- | --- |
| baz | bim |
```

| foo | bar |
| --- | --- |
| baz | bim |

Cells in a column can be aligned using the `:` character:

```md
| left | center | right |
| :--- | :----: | ----: |
| a | b | c |
```

| left | center | right |
| :--- | :----: | ----: |
| a | b | c |

:::{note}

Text is aligned by assigning `text-left`, `text-center`, or `text-right` to the cell.
It is then necessary for the theme you are using to include the appropriate css styling.

```html
<table class="colwidths-auto table">
<thead>
<tr><th class="text-left head"><p>left</p></th></tr>
</thead>
<tbody>
<tr><td class="text-left"><p>a</p></td></tr>
</tbody>
</table>
```

:::

## Images

MyST provides a few different syntaxes for including images in your documentation.
Expand Down
32 changes: 19 additions & 13 deletions myst_parser/docutils_renderer.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
MutableMapping,
Optional,
Sequence,
Tuple,
Union,
cast,
)
Expand Down Expand Up @@ -729,11 +730,9 @@ def dict_to_fm_field_list(

def render_table(self, token: SyntaxTreeNode) -> None:

assert token.children and len(token.children) > 1

# markdown-it table always contains two elements:
# markdown-it table always contains at least a header:
assert token.children
header = token.children[0]
body = token.children[1]
# with one header row
assert header.children
header_row = header.children[0]
Expand Down Expand Up @@ -761,11 +760,13 @@ def render_table(self, token: SyntaxTreeNode) -> None:
self.render_table_row(header_row)

# body
tbody = nodes.tbody()
tgroup += tbody
with self.current_node_context(tbody):
for body_row in body.children or []:
self.render_table_row(body_row)
if len(token.children) > 1:
body = token.children[1]
tbody = nodes.tbody()
tgroup += tbody
with self.current_node_context(tbody):
for body_row in body.children or []:
self.render_table_row(body_row)

def render_table_row(self, token: SyntaxTreeNode) -> None:
row = nodes.row()
Expand All @@ -776,8 +777,12 @@ def render_table_row(self, token: SyntaxTreeNode) -> None:
child.children[0].content if child.children else ""
)
style = child.attrGet("style") # i.e. the alignment when using e.g. :--
if style:
entry["classes"].append(style)
if style and style in (
"text-align:left",
"text-align:right",
"text-align:center",
):
entry["classes"].append(f"text-{cast(str, style).split(':')[1]}")
with self.current_node_context(entry, append=True):
with self.current_node_context(para, append=True):
self.render_children(child)
Expand Down Expand Up @@ -963,9 +968,10 @@ def run_directive(
self.document.current_line = position

# get directive class
directive_class, messages = directives.directive(
output: Tuple[Directive, list] = directives.directive(
name, self.language_module_rst, self.document
) # type: (Directive, list)
)
directive_class, messages = output
if not directive_class:
error = self.reporter.error(
'Unknown directive type "{}".\n'.format(name),
Expand Down
33 changes: 27 additions & 6 deletions tests/test_renderers/fixtures/tables.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,27 @@ a|b
2
.

--------------------------
Header only:
.
| abc | def |
| --- | --- |
.
<document source="notset">
<table classes="colwidths-auto">
<tgroup cols="2">
<colspec colwidth="50.0">
<colspec colwidth="50.0">
<thead>
<row>
<entry>
<paragraph>
abc
<entry>
<paragraph>
def
.

--------------------------
Aligned:
.
Expand All @@ -43,24 +64,24 @@ a | b | c
<colspec colwidth="33.33">
<thead>
<row>
<entry classes="text-align:left">
<entry classes="text-left">
<paragraph>
a
<entry classes="text-align:center">
<entry classes="text-center">
<paragraph>
b
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
c
<tbody>
<row>
<entry classes="text-align:left">
<entry classes="text-left">
<paragraph>
1
<entry classes="text-align:center">
<entry classes="text-center">
<paragraph>
2
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
3
.
Expand Down
6 changes: 3 additions & 3 deletions tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx3.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@
<entry>
<paragraph>
a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
b
<tbody>
Expand All @@ -83,15 +83,15 @@
<paragraph>
<emphasis>
a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
2
<row>
<entry>
<paragraph>
<reference refuri="https://google.com">
link-a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
<reference refuri="https://python.org">
link-b
Expand Down
6 changes: 3 additions & 3 deletions tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx4.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@
<entry>
<paragraph>
a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
b
<tbody>
Expand All @@ -83,15 +83,15 @@
<paragraph>
<emphasis>
a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
2
<row>
<entry>
<paragraph>
<reference refuri="https://google.com">
link-a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
<reference refuri="https://python.org">
link-b
Expand Down
6 changes: 3 additions & 3 deletions tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ <h1>
a
</p>
</th>
<th class="text-align:right head">
<th class="text-right head">
<p>
b
</p>
Expand All @@ -147,7 +147,7 @@ <h1>
</em>
</p>
</td>
<td class="text-align:right">
<td class="text-right">
<p>
2
</p>
Expand All @@ -161,7 +161,7 @@ <h1>
</a>
</p>
</td>
<td class="text-align:right">
<td class="text-right">
<p>
<a class="reference external" href="https://python.org">
link-b
Expand Down
6 changes: 3 additions & 3 deletions tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@
<entry>
<paragraph>
a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
b
<tbody>
Expand All @@ -84,15 +84,15 @@
<paragraph>
<emphasis>
a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
2
<row>
<entry>
<paragraph>
<reference refuri="https://google.com">
link-a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
<reference refuri="https://python.org">
link-b
Expand Down
6 changes: 3 additions & 3 deletions tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ <h1>
a
</p>
</th>
<th class="text-align:right head">
<th class="text-right head">
<p>
b
</p>
Expand All @@ -149,7 +149,7 @@ <h1>
</em>
</p>
</td>
<td class="text-align:right">
<td class="text-right">
<p>
2
</p>
Expand All @@ -163,7 +163,7 @@ <h1>
</a>
</p>
</td>
<td class="text-align:right">
<td class="text-right">
<p>
<a class="reference external" href="https://python.org">
link-b
Expand Down
6 changes: 3 additions & 3 deletions tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@
<entry>
<paragraph>
a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
b
<tbody>
Expand All @@ -84,15 +84,15 @@
<paragraph>
<emphasis>
a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
2
<row>
<entry>
<paragraph>
<reference refuri="https://google.com">
link-a
<entry classes="text-align:right">
<entry classes="text-right">
<paragraph>
<reference refuri="https://python.org">
link-b
Expand Down
3 changes: 1 addition & 2 deletions tox.ini
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,7 @@
envlist = py37-sphinx4

[testenv]
# only recreate the environment when we use `tox -r`
recreate = false
usedevelop = true

[testenv:py{36,37,38,39}-sphinx{3,4}]
deps =
Expand Down

0 comments on commit 4c8aebe

Please sign in to comment.