Jupyter-book: Need documentation for table directives

[nhanitvn]

Is your feature request related to a problem? Please describe.
I have not been able to add table directive. For example, the following does not work
{table} +--------------+----------+------------+-------+ | | Training | Validation | Test | +==============+==========+============+=======+ | Class 0 | 0 | 5 | 81 | +--------------+----------+------------+-------+ | Class 1 | 13720 | 2744 | 52136 | +--------------+----------+------------+-------+

The error is: WARNING: Error parsing content block for the "table" directive: exactly one table expected.

What should I do to make it work? I could not find any direction in the documentation. Also, after being able to make it work, how do I refer to tables like what I can do with figures?

A link to the documentation page where you see an issue.

Describe the solution you'd like

[najuzilu]

Hi @nhanitvn, according to MyST syntax documentation here the table format supported is

| a    | b    |
| :--- | ---: |
| c    | d    |

I have also been able to render:

``` {list-table}
:header-rows: 1

• 
  
  • Col1
  
  
  • Col2
  
  
• 
  
  • Row1 under Col1
  
  
  • Row1 under Col2
  
  
• 
  
  • Row2 under Col1
  
  
  • Row2 under Col2
    
    ```
    
    ``````
  
  

I just tested the table you have provided and while I don't get any errors during build, the table is not rendered (see screenshot below).

[choldgraf]

Yeah, @nhanitvn it looks like you are writing reStructuredText tables (https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables) not markdown tables. They should be fine if the rest of your page is also in rST (e.g. if the file ends in .rst) but won't work with markdown. See @najuzilu's comments above about markdown table syntax

[nhanitvn]

Thanks @najuzilu, I can confirm that I can render both of the formats that you suggested :). Now the question is how I add title for the table and a name so that I can refer to it like {numref}table_name? I tested the name tag as follow but it does not work

```{table}
:name: Train_Val_Test_distribution_1
:align: center

| a | b |
| :--- | ---: |
| c | d |

```{list-table}
:name: Train_Val_Test_distribution
:header-rows: 1
:align: center
* -    
  - Training
  - Validation
  - Test
* - Class 0
  - 0
  - 5
  - 81
* - Class 1
  - 13720
  - 2744
  - 52136

@choldgraf Yeah, I am kinda newbie to both markdown and rST. Basically, I am trying to create a report for my current project in which I work mainly on Jupyter Notebooks. Thus it is more convenient to put everything in the notebooks. But I will give rst files a try :)

[choldgraf]

@nhanitvn I'd definitely recommend just using markdown table syntax instead of rST table syntax, rather than using rST for your pages 👍

[najuzilu]

According to the Sphinx documentation here, the list-table directive takes in one possible argument which is the title.
``` {list-table} Title here
:header-rows: 1
:name: table1

• 
  
  • Col1
  
  
  • Col2
  
  
• 
  
  • Row1 under Col1
  
  
  • Row1 under Col2
  
  
• 
  
  • Row2 under Col1
  
  
  • Row2 under Col2
  
  

``````

The table can be referenced as follows

This table {numref}table1 is an example.
```

[nhanitvn]

Awesome @najuzilu . I confirm that I can render the table and refer to it now. Thanks a lot!!!