Em Mon, 7 Mar 2016 09:48:26 +0100 Johannes Stezenbach <js@xxxxxxxxxxx> escreveu: > On Mon, Mar 07, 2016 at 12:29:08AM +0100, Johannes Stezenbach wrote: > > On Sat, Mar 05, 2016 at 11:29:37PM -0300, Mauro Carvalho Chehab wrote: > > > > > > I converted one of the big tables to CSV. At least now it recognized > > > it as a table. Yet, the table was very badly formated: > > > https://mchehab.fedorapeople.org/media-kabi-docs-test/rst_tests/packed-rgb.html > > > > > > This is how this table should look like: > > > https://linuxtv.org/downloads/v4l-dvb-apis/packed-rgb.html > > > > > > Also, as this table has merged cells at the legend. I've no idea how > > > to tell sphinx to do that on csv format. > > > > > > The RST files are on this git tree: > > > https://git.linuxtv.org/mchehab/v4l2-docs-poc.git/ > > > > Yeah, seems it can't do merged cells in csv. Attached patch converts it > > back to grid table format and fixes the table definition. > > The html output looks usable, but clearly it is no fun to > > work with tables in Sphinx. > > > > Sphinx' latex writer can't handle nested tables, though. > > Python's docutils rst2latex can, but that doesn't help here. > > rst2pdf also supports it. But I have doubts such a large > > table would render OK in pdf without using landscape orientation. > > I have not tried because I used python3-sphinx but rst2pdf > > is only availble for Python2 in Debian so it does not integrate > > with Sphinx. > > Just a quick idea: > Perhaps one alternative would be to use Graphviz to render > the problematic tables, it supports a HTML-like syntax > and can be embedded in Spinx documents: > > http://www.sphinx-doc.org/en/stable/ext/graphviz.html > http://www.graphviz.org/content/node-shapes#html > http://stackoverflow.com/questions/13890568/graphviz-html-nested-tables That could work, but it is scary... Graphviz is great to generate diagrams, but it really sucks when one wants to put a graph element on a specific place, as it loves to reorder elements putting them on unexpected places. Btw, I converted all docs from our uAPI docbook to rst using pandoc. It was a brainless conversion, except for a few fixes. The output is at: https://mchehab.fedorapeople.org/media-kabi-docs-test/rst_tests/ I added it on the top of my PoC tree at: https://git.linuxtv.org/mchehab/v4l2-docs-poc.git/ Besides tables, I noticed some other bad things that needs to be corrected somehow: 1) Document divisions are not numbered. We need that. It should be broken into: - Document divisions - one per documented API: - V4L2 - Remote Controllers - DVB - Media Controller - Chapters - Sessions Everything should be numbered, as, when discussing API improvements, it is usual the need of pinpoint to an specific chapter and section. Tables and images should also be numbered, and we need a way to use references for table/image numbers. 2) Images Most images didn't popup. We have images on different file formats: - SVG - GIF - PDF - PNG 3) References It could be a conversion issue, but there are lots of missing references at the documentation. 4) We need to have some way to tell sphinx to not put some things at the lateral ToC bar. For example, at the V4L2 "Changes" section, we don't want to have one entry per version at the ToC bar. Giving that, I suspect that we'll have huge headaches to address if we use sphinx, as it seems too limited to handle complex documents. We should try to use some other tool that would give us better results. Regards, Mauro -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
