[Twisted-Python] lore2sphinx table handling?
Sphinx uses plain ReST tables, and from what I can tell, ReST has 4 (yes, 4!) ways of marking up tables: Grid tables http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tabl... - ASCII-art style tables Simple Tables http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-ta... - A different style of ASCII-art table, simpler but less powerful than Grid Tables CSV Tables http://docutils.sourceforge.net/docs/ref/rst/directives.html#csv-table - data is provided in CSV format in the body of a ReST directive List Tables http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table - data is provided as nested lists in the body of a ReST directive My question is, what format should the lore2sphinx tool target? Any of these formats should work fine, but I'm curious as to what people (in particular the core devs) think as to which should be the preferred method in the Sphinx documentation. Keep in mind that there are only 2 tables in all of the Twisted docs, and one of them is in the documentation for Lore, which (hopefully!) should be going away once this project is completed. So it's not like it would be a whole lot of work to change the preferred format later. Kevin Horn
2010/1/5 Kevin Horn <kevin.horn@gmail.com>:
Sphinx uses plain ReST tables, and from what I can tell, ReST has 4 (yes, 4!) ways of marking up tables:
Grid tables http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tabl... - ASCII-art style tables
I tend to use these, because they're what emacs' table-mode supports. But my opinion probably shouldn't count for all that much :-) Cheers, mwh
On Jan 4, 2010, at 8:21 PM, Michael Hudson-Doyle wrote:
2010/1/5 Kevin Horn <kevin.horn@gmail.com>:
Sphinx uses plain ReST tables, and from what I can tell, ReST has 4 (yes, 4!) ways of marking up tables:
Grid tables http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tabl... - ASCII-art style tables
I tend to use these, because they're what emacs' table-mode supports. But my opinion probably shouldn't count for all that much :-)
That's what I was going to say as well. I'm assuming that docutils has support for building and emitting grid tables already, though. If it's difficult to format them in the output, or the output looks weird, then I would recommend just going with CSV tables for now instead.
On Mon, Jan 04, 2010 at 06:08:17PM -0600, Kevin Horn wrote:
Any of these formats should work fine, but I'm curious as to what people (in particular the core devs) think as to which should be the preferred method in the Sphinx documentation.
I'm not a core dev, but I'll chime in so that at least you'll have some feedback if nobody else does. :) I think the List Table format is probably the easiest to maintain in a simple text editor, followed by the Simple Table format. CSV mode looks like it's really designed for you to keep the table in an external file and edit it in a spreadsheet, or regenerate it from a database, and while Grid Tables look pretty, actually editing them requires an Emacs mode, or a lot of patience.
On Jan 4, 2010, at 8:32 PM, Tim Allen wrote:
I think the List Table format is probably the easiest to maintain in a simple text editor, followed by the Simple Table format. CSV mode looks like it's really designed for you to keep the table in an external file and edit it in a spreadsheet, or regenerate it from a database, and while Grid Tables look pretty, actually editing them requires an Emacs mode, or a lot of patience.
But when you *do* have an emacs mode (and, really, doesn't everynoe?) it's the easiest to use. James
On Mon, Jan 04, 2010 at 11:23:37PM -0500, James Y Knight wrote:
On Jan 4, 2010, at 8:32 PM, Tim Allen wrote:
while Grid Tables look pretty, actually editing them requires an Emacs mode, or a lot of patience.
But when you *do* have an emacs mode (and, really, doesn't everynoe?)
Well, no, no I don't. Does that mean I don't have to supply documentation changes with any patches I supply in future? ;)
On Mon, Jan 4, 2010 at 10:53 PM, Tim Allen <screwtape@froup.com> wrote:
On Mon, Jan 04, 2010 at 11:23:37PM -0500, James Y Knight wrote:
On Jan 4, 2010, at 8:32 PM, Tim Allen wrote:
while Grid Tables look pretty, actually editing them requires an Emacs mode, or a lot of patience.
But when you *do* have an emacs mode (and, really, doesn't everynoe?)
Well, no, no I don't. Does that mean I don't have to supply documentation changes with any patches I supply in future? ;)
Well, I don't use Emacs (at least I haven't in about 12+ years) but seeing as how there will only be 1 relatively modest table in the docs (unless someone adds more), I think we can live with the pain of hand-editing Grid tables, so I'll likely use eitehr them or simple tables. Thanks for the feedback everyone! Kevin Horn
participants (5)
-
Glyph Lefkowitz -
James Y Knight -
Kevin Horn -
Michael Hudson-Doyle -
Tim Allen