Re: Kernel docs: muddying the waters a bit

[Johannes Stezenbach]

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.


Johannes
>From 61674b398e778bd5ff644ffd493d5ff1cfaca0ef Mon Sep 17 00:00:00 2001
From: Johannes Stezenbach <j...@sig21.net>
Date: Sun, 6 Mar 2016 23:55:19 +0100
Subject: [PATCH] some progress for html output

---
 _static/borderless.css |  3 --
 _static/v4l2tables.css |  9 +
 _templates/layout.html |  9 +
 packed-rgb.rst | 88 +-
 pixfmt-yuyv.rst|  2 +-
 v4l-table-within-table.rst | 72 +++--
 6 files changed, 105 insertions(+), 78 deletions(-)
 delete mode 100644 _static/borderless.css
 create mode 100644 _static/v4l2tables.css

diff --git a/_static/borderless.css b/_static/borderless.css
deleted file mode 100644
index bfd4b01..000
--- a/_static/borderless.css
+++ /dev/null
@@ -1,3 +0,0 @@
-table#table-borderless {
-border: 1px solid black;
-}
diff --git a/_static/v4l2tables.css b/_static/v4l2tables.css
new file mode 100644
index 000..c045e45
--- /dev/null
+++ b/_static/v4l2tables.css
@@ -0,0 +1,9 @@
+table.noborder {
+border: 1px solid black;
+background: white;
+white-space: nowrap;
+}
+
+table.noborder td, table.noborder th {
+padding: 0px;
+}
diff --git a/_templates/layout.html b/_templates/layout.html
index b6bf12b..637332d 100644
--- a/_templates/layout.html
+++ b/_templates/layout.html
@@ -1,9 +1,2 @@
 {% extends "!layout.html" %}
-{% block tables %}
-
-table#table-borderless {
-border: 1px solid black;
-}
-
-{{ super() }}
-{% endblock %}
+{% set css_files = css_files + ["_static/v4l2tables.css"] %}
diff --git a/packed-rgb.rst b/packed-rgb.rst
index 352b91c..b4fcf3e 100644
--- a/packed-rgb.rst
+++ b/packed-rgb.rst
@@ -9,25 +9,46 @@ graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
 These are all packed-pixel formats, meaning all the data for a pixel lie
 next to each other in memory.
 
-.. csv-table:: Table: Packed RGB Image Formats
-  :header: Identifier,Code, ,Byte 0 in memory,Byte 1,Byte 2,Byte 3
+.. table:: Packed RGB Image Formats
+   :class: noborder
 
-  ``V4L2_PIX_FMT_RGB332``,'RGB1',,r\ :sub:`2`,r\ :sub:`1`,r\ :sub:`0`,g\ :sub:`2`,g\ :sub:`1`,g\ :sub:`0`,b\ :sub:`1`,b\ :sub:`0`
-  ``V4L2_PIX_FMT_ARGB444``,'AR12',,g\ :sub:`3`,g\ :sub:`2`,g\ :sub:`1`,g\ :sub:`0`,b\ :sub:`3`,b\ :sub:`2`,b\ :sub:`1`,b\ :sub:`0`,,a\ :sub:`3`,a\ :sub:`2`,a\ :sub:`1`,a\ :sub:`0`,r\ :sub:`3`,r\ :sub:`2`,r\ :sub:`1`,r\ :sub:`0`
-  ``V4L2_PIX_FMT_XRGB444``,'XR12',,g\ :sub:`3`,g\ :sub:`2`,g\ :sub:`1`,g\ :sub:`0`,b\ :sub:`3`,b\ :sub:`2`,b\ :sub:`1`,b\ :sub:`0`,,-,-,-,-,r\ :sub:`3`,r\ :sub:`2`,r\ :sub:`1`,r\ :sub:`0`
-  ``V4L2_PIX_FMT_ARGB555``,'AR15',,g\ :sub:`2`,g\ :sub:`1`,g\ :sub:`0`,b\ :sub:`4`,b\ :sub:`3`,b\ :sub:`2`,b\ :sub:`1`,b\ :sub:`0`,,a,r\ :sub:`4`,r\ :sub:`3`,r\ :sub:`2`,r\ :sub:`1`,r\ :sub:`0`,g\ :sub:`4`,g\ :sub:`3`
-  ``V4L2_PIX_FMT_XRGB555``,'XR15',,g\ :sub:`2`,g\ :sub:`1`,g\ :sub:`0`,b\ :sub:`4`,b\ :sub:`3`,b\ :sub:`2`,b\ :sub:`1`,b\ :sub:`0`,,-,r\ :sub:`4`,r\ :sub:`3`,r\ :sub:`2`,r\ :sub:`1`,r\ :sub:`0`,g\ :sub:`4`,g\ :sub:`3`
-  ``V4L2_PIX_FMT_RGB565``,'RGBP',,g\ :sub:`2`,g\ :sub:`1`,g\ :sub:`0`,b\ :sub:`4`,b\ :sub:`3`,b\ :sub:`2`,b\ :sub:`1`,b\ :sub:`0`,,r\ :sub:`4`,r\ :sub:`3`,r\ :sub:`2`,r\ :sub:`1`,r\ :sub:`0`,g\ :sub:`5`,g\ :sub:`4`,g\ :sub:`3`
-  ``V4L2_PIX_FMT_ARGB555X``,'AR15' | (1<<31),,a,r\ :sub:`4`,r\ :sub:`3`,r\ :sub:`2`,r\ :sub:`1`,r\ :sub:`0`,g\ :sub:`4`,g\ :sub:`3`,,g\ :sub:`2`,g\ :sub:`1`,g\ :sub:`0`,b\ :sub:`4`,b\ :sub:`3`,b\ :sub:`2`,b\ :sub:`1`,b\ :sub:`0`
-  ``V4L2_PIX_FMT_XRGB555X``,'XR15' | (1<<31),,-,r\ :sub:`4`,r\ :sub:`3`,r\ :sub:`2`,r\ :sub:`1`,r\ :sub:`0`,g\ :sub:`4`,g\ :sub:`3`,,g\ :sub:`2`,g\ :sub:`1`,g\ :sub:`0`,b\ :sub:`4

Re: Kernel docs: muddying the waters a bit

[Johannes Stezenbach]

On Fri, Mar 04, 2016 at 10:29:08AM +0200, Jani Nikula wrote:
> On Fri, 04 Mar 2016, Mauro Carvalho Chehab  wrote:
> >
> > If, on the other hand, we decide to use RST, we'll very likely need to
> > patch it to fulfill our needs in order to add proper table support.
> > I've no idea how easy/difficult would be to do that, nor if Sphinx
> > upstream would accept such changes.
> >
> > So, at the end of the day, we may end by having to carry on our own
> > version of Sphinx inside our tree, with doesn't sound good, specially
> > since it is not just a script, but a package with hundreds of
> > files.
> 
> If we end up having to modify Sphinx, it has a powerful extension
> mechanism for this. We wouldn't have to worry about getting it merged to
> Sphinx upstream, and we wouldn't have to carry a local version of all of
> Sphinx. (In fact, the extension mechanism provides a future path for
> doing kernel-doc within Sphinx instead of as a preprocessing step.)
> 
> I know none of this alleviates your concerns with table supports right
> now. I'll try to have a look at that a bit more.

FWIW, I think table formatting in Sphinx works via style sheets.
The mechanism is documented in the Python docutils docs that
Sphinx is built upon.
Basically you use the "class" or "role" directive and define
the corresponding CSS or LaTeX (or rst2pdf) style.

Here is one example (using a custom "cssclass" role):
https://pythonhosted.org/sphinxjp.themes.basicstrap/sample.html

Directives (especially role and class):
http://www.sphinx-doc.org/en/stable/rest.html#directives

LaTeX styling:
http://docutils.readthedocs.org/en/sphinx-docs/user/latex.html#custom-interpreted-text-roles


HTH,
Johannes
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html