How do I use docutils to make a caption for a table?

[Peter Burdine]

I'm working on extension that creates a table programmatically, but I can't seem to figure out how to add a caption to a table.

When you create a table, you need to make the following:

• Make nodes.table
• Make nodes.tgroup
• Add tgroup to the table
  
• Add headers to the the tgroup
• Add colspecs to the tgroup
• Make nodes.thead
• Add thead to tgroup
• Add rows to thead
• Make nodes.tbody
• Add contents to the table
• Add the table

I'm trying to then create a caption like: 

caption = nodes.caption('', '', nodes.Text('Caption Text'))

But it doesn't seem to matter where I try to add the caption, it doesn't work.  So far I have been unable to locate an example of how to do this.  Can someone help me out?

Thanks,

Peter

[Guenter Milde]

On 2016-07-20, Peter Burdine wrote:

> [-- Type: text/plain, Encoding: --]

> I'm working on extension that creates a table programmatically, but I can't
> seem to figure out how to add a caption to a table.

> When you create a table, you need to make the following:

> - Make nodes.table
> - Make nodes.tgroup
> - Add tgroup to the table
> - Add headers to the the tgroup
> - Add colspecs to the tgroup
> - Make nodes.thead
> - Add thead to tgroup
> - Add rows to thead
> - Make nodes.tbody
> - Add contents to the table
> - Add the table

> I'm trying to then create a caption like:

> caption = nodes.caption('', '', nodes.Text('Caption Text'))

> But it doesn't seem to matter where I try to add the caption, it doesn't
> work. So far I have been unable to locate an example of how to do this.
> Can someone help me out?

reStructuredText has a "table" directive that creates a "formal table" with
caption.

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

Have a look at the native XML (or pseudoXML) output of a document with the
desired content ("hand input" as rST).
(You may find an example also in the Docutils tests in
.../test/functional/expected/standalone_rst_pseudoxml.txt)

Hope this helps.

Günter

[Peter Burdine]

Thank you for the suggestion, It got me a bit further (a table gets a Title, not a Caption, go figure).  It may or may not be the right approach, but this is how I got it to work.

I had to create 2 new classes, one directive, one node.  The directive had to be a subclass of the Table directive.  I could only get the caption to show up by calling Table.make_title().  Anything else I tried would create a title, but it wouldn't get numfig_format applied to it (eg it would be "Title" instead of "Table X: Title"), and it would be in the table of tables.

The other class was empty. 

Then in post processing, I replace the empty class with a tgroup with the data I wanted.

[Guenter Milde]

On 2016-07-22, Peter Burdine wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Thank you for the suggestion, It got me a bit further (a table gets a
> Title, not a Caption, go figure). It may or may not be the right approach,
> but this is how I got it to work.

> I had to create 2 new classes, one directive, one node. The directive had
> to be a subclass of the Table directive. I could only get the caption to
> show up by calling Table.make_title(). Anything else I tried would create
> a title, but it wouldn't get numfig_format applied to it (eg it would be
> "Title" instead of "Table X: Title"), and it would be in the table of
> tables.

> The other class was empty.

> Then in post processing, I replace the empty class with a tgroup with the
> data I wanted.

I don't know what you mean exactly with post-processing.
However, the CSVTable and ListTable classes in
docutils/docutils/parsers/rst/directives/tables.py
should give you examples of table-generating directives.

Günter

[Peter Burdine]

I am sorry, I should have been more specific, I meant I need to build the table during the doctree-resolved event.

Here is how I had to make the table directive in case anyone else needs it:

class CustomTableDirective(Table):
    def run(self):
        env = self.state.document.settings.env
        app = env.app
        config = app.config
        # I know what the table title should always be, so ignore the reST input
        self.arguments = ['My Table Title/Caption']
        title, messages = self.make_title()
        table = nodes.table()
        table.insert(0, title)
        table += my_custom_class_that_will_be_replaced()
        return [table]