From 86cfafcc05360eb3ffff12e53982f798286635fa Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Sat, 4 Dec 2021 13:08:09 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=91=8C=20IMPROVE:=20Table=20rendering?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change cell alignment classes to `text-left`, `text-center`, or `text-right`, and allow tables with no body. --- docs/syntax/syntax.md | 44 +++++++++++++++++++ myst_parser/docutils_renderer.py | 32 ++++++++------ tests/test_renderers/fixtures/tables.md | 33 +++++++++++--- .../test_basic.resolved.sphinx3.xml | 6 +-- .../test_basic.resolved.sphinx4.xml | 6 +-- .../test_basic.sphinx3.html | 6 +-- .../test_sphinx_builds/test_basic.sphinx3.xml | 6 +-- .../test_basic.sphinx4.html | 6 +-- .../test_sphinx_builds/test_basic.sphinx4.xml | 6 +-- tox.ini | 3 +- 10 files changed, 109 insertions(+), 39 deletions(-) diff --git a/docs/syntax/syntax.md b/docs/syntax/syntax.md index 0f25c14f..23e22d3d 100644 --- a/docs/syntax/syntax.md +++ b/docs/syntax/syntax.md @@ -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 + + + + + + + +

left

a

+``` + +::: + ## Images MyST provides a few different syntaxes for including images in your documentation. diff --git a/myst_parser/docutils_renderer.py b/myst_parser/docutils_renderer.py index e5b580fe..748882b5 100644 --- a/myst_parser/docutils_renderer.py +++ b/myst_parser/docutils_renderer.py @@ -15,6 +15,7 @@ MutableMapping, Optional, Sequence, + Tuple, Union, cast, ) @@ -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] @@ -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() @@ -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) @@ -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), diff --git a/tests/test_renderers/fixtures/tables.md b/tests/test_renderers/fixtures/tables.md index f962cfc4..fe0e39b3 100644 --- a/tests/test_renderers/fixtures/tables.md +++ b/tests/test_renderers/fixtures/tables.md @@ -28,6 +28,27 @@ a|b 2 . +-------------------------- +Header only: +. +| abc | def | +| --- | --- | +. + + + + + + + + + + abc + + + def +. + -------------------------- Aligned: . @@ -43,24 +64,24 @@ a | b | c - + a - + b - + c - + 1 - + 2 - + 3 . diff --git a/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx3.xml b/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx3.xml index bdf86389..2f4a8ec0 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx3.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx3.xml @@ -74,7 +74,7 @@ a - + b @@ -83,7 +83,7 @@ a - + 2 @@ -91,7 +91,7 @@ link-a - + link-b diff --git a/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx4.xml b/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx4.xml index ea2a20e7..c37558e1 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx4.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_basic.resolved.sphinx4.xml @@ -74,7 +74,7 @@ a - + b @@ -83,7 +83,7 @@ a - + 2 @@ -91,7 +91,7 @@ link-a - + link-b diff --git a/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.html b/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.html index 3f6635de..75f6db91 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.html +++ b/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.html @@ -131,7 +131,7 @@

a

-

- @@ -84,7 +84,7 @@ a - + 2 @@ -92,7 +92,7 @@ link-a - + link-b diff --git a/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.html b/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.html index 59e0769a..555bc855 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.html +++ b/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.html @@ -133,7 +133,7 @@

a

-

- @@ -84,7 +84,7 @@ a - + 2 @@ -92,7 +92,7 @@ link-a - + link-b diff --git a/tox.ini b/tox.ini index fa662086..c826391d 100644 --- a/tox.ini +++ b/tox.ini @@ -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 =
+

b

@@ -147,7 +147,7 @@

-

+

2

@@ -161,7 +161,7 @@

+

link-b diff --git a/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.xml b/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.xml index 841746d8..04155870 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx3.xml @@ -75,7 +75,7 @@ a - + b

+

b

@@ -149,7 +149,7 @@

-

+

2

@@ -163,7 +163,7 @@

+

link-b diff --git a/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.xml b/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.xml index a9f3f35d..71c92848 100644 --- a/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.xml +++ b/tests/test_sphinx/test_sphinx_builds/test_basic.sphinx4.xml @@ -75,7 +75,7 @@ a - + b