Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Wed, 5 Oct 2022 06:59:09 +0100
From:   Mauro Carvalho Chehab <mchehab@kernel.org>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Jani Nikula <jani.nikula@linux.intel.com>
Subject: Re: [PATCH 5/5] docs: improve the HTML formatting of kerneldoc
 comments
Message-ID: <20221005065909.33ba2523@sal.lan>
In-Reply-To: <20221004201222.281845-6-corbet@lwn.net>
References: <20221004201222.281845-1-corbet@lwn.net>
        <20221004201222.281845-6-corbet@lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

Em Tue,  4 Oct 2022 14:12:22 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Make a few changes to cause functions documented by kerneldoc to stand out
> better in the rendered documentation.  Specifically, change kernel-doc to
> put the description section into a ".. container::" section, then add a bit
> of CSS to indent that section relative to the function prototype (or struct
> or enum definition).  Tweak a few other CSS parameters while in the
> neighborhood to improve the formatting.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/sphinx-static/custom.css | 13 +++++++
>  scripts/kernel-doc                     | 52 ++++++++++++++++----------
>  2 files changed, 45 insertions(+), 20 deletions(-)
> 
> diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
> index c465251e840a..d8823fbbd27b 100644
> --- a/Documentation/sphinx-static/custom.css
> +++ b/Documentation/sphinx-static/custom.css
> @@ -10,3 +10,16 @@ div.body h3 { font-size: 130%; }
>  
>  /* Tighten up the layout slightly */
>  div.body { padding: 0 15px 0 10px; }
> +
> +/* Don't force the document width */
> +div.document { width: auto; max-width: 60em; }
> +
> +/*
> + * Parameters for the display of function prototypes and such included
> + * from C source files.
> + */
> +dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; }
> +/* indent lines 2+ of multi-line function prototypes */
> +dl.function dt { margin-left: 10em; text-indent: -10em; }
> +dt.sig-object { font-size: larger; }
> +div.kernelindent { margin-left: 2em; margin-right: 4em; }
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index aea04365bc69..13d42857bce2 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -866,48 +866,53 @@ sub output_function_rst(%) {
>  	print "\n";
>      }
>  
> -    print "**Parameters**\n\n";
> +    #
> +    # Put our descriptive text into a container (thus an HTML <div> to help
> +    # set the function prototypes apart.

Nitpick: you forgot to close the parenthesis on your comment ;-)

> +    #
> +    print ".. container:: kernelindent\n\n";

I liked the new alignment: it makes easier to identify what belongs
to each definition block.

As I didn't test the patches, it sounds worth mentioning that it makes
sense to check if this won't badly affect epub and/or LaTeX/PDF outputs.

The LaTeX output generator in particular has a problem with long
lines with fixed-width lines: if the text doesn't fit into one line, it
either truncates it or makes the text go outside the margins.

If the container affects the PDF outputs, we need to double-check if
this would break its output.

Also, when the container directive was introduced? Does it affect
the minimal Sphinx version we support? It seems that this was old
enough to not require any changes at the minimal version, but,
from https://www.sphinx-doc.org/en/master/changes.html, it seems
that LaTeX support for it was added only at Sphinx v4.1 on this PR:

	https://github.com/sphinx-doc/sphinx/pull/9166

So, we need to double-check if are there any changes before and after
such version at the places container is used - or change the kerneldoc
to only emit such tags on PDF depending on the Sphinx version.

Regards,
Mauro