On Mon, 20 Sep 2021, Akira Yokosawa akiyks@gmail.com wrote:

Nested grids in grid-table cells are not specified as proper ReST constructs. Commit 572f2a5cd974 ("drm/i915/guc: Update firmware to v62.0.0") added a couple of kerneldoc tables of the form:

+---+-------+------------------------------------------------------+ | 1 | 31:0 | +------------------------------------------------+ | +---+-------+ | | | |...| | | Embedded `HXG Message`_ | | +---+-------+ | | | | n | 31:0 | +------------------------------------------------+ | +---+-------+------------------------------------------------------+

For "make htmldocs", they happen to work as one might expect, but they are incompatible with "make latexdocs" and "make pdfdocs", and cause the generated gpu.tex file to become incomplete and unbuildable by xelatex.

Restore the compatibility by removing those nested grids in the tables.

Size comparison of generated gpu.tex:

              Sphinx 2.4.4  Sphinx 4.2.0

v5.14: 3238686 3841631 v5.15-rc1: 376270 432729 with this fix: 3377846 3998095

Fixes: 572f2a5cd974 ("drm/i915/guc: Update firmware to v62.0.0") Cc: John Harrison John.C.Harrison@Intel.com Cc: Michal Wajdeczko michal.wajdeczko@intel.com Cc: Matthew Brost matthew.brost@intel.com Cc: Daniele Ceraolo Spurio daniele.ceraolospurio@intel.com Cc: Matt Roper matthew.d.roper@intel.com Cc: Jonathan Corbet corbet@lwn.net Signed-off-by: Akira Yokosawa akiyks@gmail.com

Pushed to drm-intel-gt-next, thanks for the patch.

This makes the HTML output arguably worse, but there were no comments from anyone and the pdf build needs to work.

BR, Jani.

---

Hi all,

I know there is little interest in building pdfdocs (or LaTeX) version of kernel-doc, and this issue does not matter most of you.

But "make pdfdocs" is supposed to work, give or take those tables with squeezed columns, and at least it is expected to complete without fatal errors.

I have no idea who is responsible to those grid-tables, so added a lot of people in the To: and Cc: lists.

Does removing those nested grids look reasonable to you?

Any feedback is welcome!

Note: This patch is against the docs-next branch of Jon's -doc tree (git://git.lwn.net/linux.git). It can be applied against v5.15-rc1 and v5.15-rc2 as well.

    Thanks, Akira

-- .../gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h | 10 +++++----- .../drm/i915/gt/uc/abi/guc_communication_mmio_abi.h | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h b/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h index 99e1fad5ca20..c9086a600bce 100644 --- a/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h +++ b/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_ctb_abi.h @@ -102,11 +102,11 @@ static_assert(sizeof(struct guc_ct_buffer_desc) == 64);

• | +-------+--------------------------------------------------------------+
• | | 7:0 | NUM_DWORDS = length (in dwords) of the embedded HXG message |
• +---+-------+--------------------------------------------------------------+

• • | 1 | 31:0 | +--------------------------------------------------------+ |
• • +---+-------+ | | |
• • |...| | | Embedded `HXG Message`_ | |
• • +---+-------+ | | |
• • | n | 31:0 | +--------------------------------------------------------+ |

• • | 1 | 31:0 | |
• • +---+-------+ |
• • |...| | [Embedded `HXG Message`_] |
• • +---+-------+ |
• • | n | 31:0 | |
  • +---+-------+--------------------------------------------------------------+
  */

diff --git a/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h b/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h index bbf1ddb77434..9baa3cb07d13 100644 --- a/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h +++ b/drivers/gpu/drm/i915/gt/uc/abi/guc_communication_mmio_abi.h @@ -38,11 +38,11 @@

• +---+-------+--------------------------------------------------------------+
• | | Bits | Description |
• +===+=======+==============================================================+

• • | 0 | 31:0 | +--------------------------------------------------------+ |
• • +---+-------+ | | |
• • |...| | | Embedded `HXG Message`_ | |
• • +---+-------+ | | |
• • | n | 31:0 | +--------------------------------------------------------+ |

• • | 0 | 31:0 | |
• • +---+-------+ |
• • |...| | [Embedded `HXG Message`_] |
• • +---+-------+ |
• • | n | 31:0 | |
  • +---+-------+--------------------------------------------------------------+
  */

base-commit: 242f4c77b1c8cebfdfa0ad5b40e2e4ae0316e57d