Re: [Intel-gfx] [PATCH] drm/i915/guc, docs: Fix pdfdocs build error by removing nested grid

[Jani Nikula <jani.nikula@linux.intel.com>]

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>
> ---
> 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.

Absolutely!

> 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.

I think this should go through drm-intel, and it'll find its way back to
some v5.15-rc.

BR,
Jani.

>
>         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

-- 
Jani Nikula, Intel Open Source Graphics Center