Support tables

[lu-zero]

docutils has some table support, would be nice to provide a kramdown compatible table support.

[sid-kap]

+1

[richterb]

Agreed! Tables can be very useful when writing documentation, and when using Sphinx, it feels a bit bad to choose between writing a huge block of HTML or switching to RST just for one page.

[marcelstoer]

+1

Tables are essential for docs. If MkDocs offered better "project structuring" options (i.e. TOC options) I'd much rather use Read the Docs & MkDocs than Read the Docs & Sphinx & recommonmark. I simply don't understand why the CommonMark community is so reluctant to adopt it. It's gonna take ages until it's in CommonMark (see http://talk.commonmark.org/t/tables-in-pure-markdown/81).

[moorchegue]

+1

[agjohnson]

My opinion on how we're using the CommonMark spec is starting to shift slightly. Personally, I'm still -1 on shoveling syntax on top of CommonMark, lest we end up with another Markdown tire fire. I do however think we could afford to prematurely adopt a CommonMark extension syntax as an experimental feature.

This would greatly improve the table authoring experience, giving authors access to docutils directives like csv-table[1], rather than support the authoring nightmare that is plain text tables.

I'm curious to know what authors here would think of this change compared to table syntax support.

1: http://docutils.sourceforge.net/docs/ref/rst/directives.html#id4

[nowox]

+1

[tigerhawkvok]

👍 It was unexpected enough that this somehow isn't implemented I thought it was actually a bug at first, till I saw commonmark/commonmark-spec#73 .

I think MarkdownExtra / GFM tables are better than the "table syntax support", @agjohnson -- if you're already used to Markdown, especially on most websites, using RST syntax would "break expectations", whereas implementing this would conform to expectations instead.

[agjohnson]

There's no rST required in my suggestion, it would be a Markdown extension syntax chosen from the current discussion on the commonmark spec around extensions. It's also something this module will adopt as soon as the extension spec is ratified. It wouldn't be a standard addition that other flavors/etc of markdown support, but ¯_(ツ)_/¯ what is.

I do agree missing a table syntax would be an abrupt change for anyone more familiar with $Whatever Flavored Markdown. Perhaps table syntax could be another feature we preemptively adopt from the commonmark spec discussions as an experimental feature.

I also think most authors have varying degrees of Stockholm Syndrome when it comes to the deficiencies of authoring complex documents with markdown. Table syntax inside any markup language -- rST included -- is an utterly broken experience for authors. Docutils provides an infinitely better experience for managing large tables outside of the markup syntax. Short tables are of course better served by a native markup table syntax, though.

[marcelstoer]

I also think most authors have varying degrees of Stockholm Syndrome when it comes to the deficiencies of authoring complex documents with markdown.

LOL, nice one 😆 Never thought about it but associating this with Stockholm Syndrome is spot-on.

Docutils provides an infinitely better experience for managing large tables outside of the markup syntax.

Didn't know about Docutils until you mentioned in your previous comment. I agree that it probably provides a much better experience. The reason why I'd still use native markup table syntax (even if Docutils directives were available) is that those tables would render just fine when viewed on GitHub.

[brainwane]

My use case: our Read the Docs documentation is currently a mix of reStructuredText and Markdown. We'd like to unify (as much as possible) on Markdown (zulip/zulip#668), so it's easier for people to make improvements to existing docs (since GitHub lets a user preview changes to a Markdown file in its web UI). I would like to continue to use tables for this explanation of our directory structure.

The October 2015 announcement that Read the Docs would support Commonmark via recommonmark did say the intended usage was "basic text formatting and links" for "FAQ’s, blog posts, and other less reference heavy content" -- so if recommonmark and the CommonMark spec are not going to support tables then I'll understand.

[pfultz2]

So, I use embedded rst tables using the eval_rst. I wonder if for the short term, it could pass an rst table on to the eval_rst automatically. This might be simpler than extended commonmark to support tables.

[agjohnson]

Okay, so I believe I'll take a stab at this tomorrow. I'm proficient enough with this package and the CommonMark package, though the problem of parsing table syntaxes sounds utterly awful. The next question is this:

Do we keep CommonMark vanilla CommonMark, and instead subclass or patch the CommonMark.Parser, or would experimental CommonMark spec features make more sense in the CommonMark package?

I'll raise this question in readthedocs/commonmark.py#28 as well

[mblaettler]

What is the process regarding this issue?

I'd really like to use tables within markdown, because I intended to switch from mkdocs to sphinx and I'd like to keep most of my documentation unchanged.

I was thinking about introducing a new AutoStructify configuration to enable experimental table support. My idea would be to convert the table from Markdown to rst on the fly and pass it further to the method which evaluates inline rst.
What would you guys think of this approach?

[marcelstoer]

Is it helpful to study the GitHub approach for hints (and maybe code)? In https://githubengineering.com/a-formal-spec-for-github-markdown/ they outlined their reasoning for forking cmark and then writing specific extensions (tables et.al.) in https://github.com/github/cmark/tree/master/extensions.

[mblaettler]

Thanks @marcelstoer it was an interesting read. I think such an approach would be the best option, although I'm not quite sure, how/where to implement it in this project.
Does anybody have an idea? IMO this must be done within commonmark and not recommonmark.

I just did a proof-of-concept of my approach introduced in my previous comment, I'd be happy to get your feedback. See pull request #68 .

[agjohnson]

Yeah, i lean toward implementing this as an extension to commonmark, as some form of "experimental" extension that is likely to change. I spent some time on the commonmark spec discussion page, and think that gfm tables is probably the most accepted solution. I got stuck on actually digging through py-commonmark though, extending the parser wasn't intuitive and was going to be more than a weekend worth of work.

[q10]

What is the ETA for this feature?

[cdanger]

+1

[yishenggudou]

+1

[STRML]

While I haven't personally evaluated its correctness, it appears this was implemented in https://github.com/GovReady/CommonMark-py-Extensions. Is there any desire at RTD to get this in to support tables for their users?

[leniy]

@STRML How to use your repo in sphinx?

[ryanfox]

I wrote a sphinx extension to render tables in markdown. The source is here.

I uploaded it to pypi here. It's installable via pip install sphinx-markdown-tables.

[leniy]

@ryanfox THX a lot

[barbara-sfx]

I wrote a sphinx extension to render tables in markdown. The source is here.

I uploaded it to pypi here. It's installable via pip install sphinx-markdown-tables.

Hi, and thanks. I supposedly installed it correctly....

Collecting sphinx-markdown-tables
  Downloading https://files.pythonhosted.org/packages/3d/d0/4f6e12f06f87bcae7a97997fc50862222ee78f859edece0da0ad75d8ada4/sphinx-markdown-tables-0.0.9.tar.gz
Collecting markdown==2.6.11 (from sphinx-markdown-tables)
  Downloading https://files.pythonhosted.org/packages/6d/7d/488b90f470b96531a3f5788cf12a93332f543dbab13c423a5e7ce96a0493/Markdown-2.6.11-py2.py3-none-any.whl (78kB)
    100% |████████████████████████████████| 81kB 4.7MB/s 
Installing collected packages: markdown, sphinx-markdown-tables
  Running setup.py install for sphinx-markdown-tables ... done
Successfully installed markdown-2.6.11 sphinx-markdown-tables-0.0.9

And I added it to my conf.py file:

extensions = [
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.ifconfig',
    'tagging',
    'toggle',
    'newpage',
    'recommonmark',
    'sphinx-markdown-tables',
]

but I get this error:
Running Sphinx v1.8.2

Extension error:
Could not import extension sphinx-markdown-tables (exception: No module named sphinx-markdown-tables)
make: *** [html] Error 2

I'm far from a command-line expert. Did I miss a step somewhere? I just installed recommonmark and it seemed to work fine.

I thought maybe I also had to add the markdown extension in conf.py, but when I did that I saw:

WARNING: extension 'markdown' has no setup() function; is it really a Sphinx extension module?

TIA

[ryanfox]

I would double check that you installed sphinx-markdown-tables to the right python environment. My guess is that sphinx can't see sphinx-markdown-tables because it got installed to (e.g.) a different virtualenv.

[barbara-sfx]

Turns out that the directory name has underlines instead of hyphens, which I didn't notice before. It is working now. Yay!

[clayrisser]

@agjohnson
@brainwane
@leniy
@lu-zero
@marcelstoer
@mblaettler
@tigerhawkvok

@aborruso, (sphinx-markdown-tables)[https://github.com/ryanfox/sphinx-markdown-tables] is not true sphinx/docutils table support. It simply converts the tables to html tables. This creates major issues when writing custom sphinx builders/writers.

For example when building the sphinx-markdown-builder, I walk the docutils tree to build markdown tables. However, this fails to work with an html table. So, I have to build a custom exception that detects html tables to convert it to a markdown table. This is certainly not ideal, because someone might explicitly define their table in html and want it kept in html. In summary, html tables should be separate from a docutils table, and recommonmark should build a docutils table from markdown tables to ensure this separation.

Sadly, the commonmark python module does not support parsing markdown tables. It has been suggested to rebuild the recommonmark parser to use the Markdown python module. This parser supports extensions and has a very solid extension for parsing markdown tables.

I have created a pull request to add the Markdown parser.
#138

It not only enables full markdown support using the Markdown python module but also opens the door for more features supported by the Markdown modules various extensions.

I have ensured the pull request is fully backward compatible with the CommonMark parser.

In order to use the Markdown parser this pull request implements, you have to explicitly set the parser property in the recommonmark_config to Markdown.

    app.add_config_value('recommonmark_config', {
        'parser': 'Markdown'
    }, True)

You can see my code at the link below.
https://github.com/codejamninja/recommonmark/tree/codejamninja/python-markdown

[simonsan]

This is working https://github.com/ryanfox/sphinx-markdown-tables

[soodifficult]

@ryanfox I modified conf.py referring to here. But it still prompts me when RTD generates documents ModuleNotFoundError: No module named 'sphinx_markdown_tables'. Follow is my conf.py:

project = u'InGateway'
copyright = u'2019, zhangning'
author = u'zhangning'

version = u''

release = u'0.0.1'

extensions = [
'sphinx_markdown_tables', 'recommonmark',
]

templates_path = ['_templates']

source_parsers = {
'.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

master_doc = 'index'

language = u'zh_CN'

exclude_patterns = []

pygments_style = None

html_style = 'css/docs.css'
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_logo = "_static/logo.png"

html_static_path = ['_static']

latex_elements = {
}

latex_documents = [
(master_doc, 'InGateway.tex', u'InGateway Documentation',
u'zhangning', 'manual'),
]

man_pages = [
(master_doc, 'InGateway', u'InGateway Documentation',
[author], 1)
]