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.

Sign up for GitHub

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

Jump to bottom

👌 IMPROVE: Table rendering #450

Merged
merged 1 commit into from
Dec 4, 2021
Merged

👌 IMPROVE: Table rendering #450

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/syntax/syntax.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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