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 <[email protected]>
---
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.
+ #
+ print ".. container:: kernelindent\n\n";
$lineprefix = " ";
+ print $lineprefix . "**Parameters**\n\n";
foreach $parameter (@{$args{'parameterlist'}}) {
my $parameter_name = $parameter;
$parameter_name =~ s/\[.*//;
$type = $args{'parametertypes'}{$parameter};
if ($type ne "") {
- print "``$type``\n";
+ print $lineprefix . "``$type``\n";
} else {
- print "``$parameter``\n";
+ print $lineprefix . "``$parameter``\n";
}
print_lineno($parameterdesc_start_lines{$parameter_name});
+ $lineprefix = " ";
if (defined($args{'parameterdescs'}{$parameter_name}) &&
$args{'parameterdescs'}{$parameter_name} ne $undescribed) {
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
} else {
- print " *undescribed*\n";
+ print $lineprefix . "*undescribed*\n";
}
+ $lineprefix = " ";
print "\n";
}
- $lineprefix = $oldprefix;
output_section_rst(@_);
+ $lineprefix = $oldprefix;
}
sub output_section_rst(%) {
my %args = %{$_[0]};
my $section;
my $oldprefix = $lineprefix;
- $lineprefix = "";
foreach $section (@{$args{'sectionlist'}}) {
- print "**$section**\n\n";
+ print $lineprefix . "**$section**\n\n";
print_lineno($section_start_lines{$section});
output_highlight_rst($args{'sections'}{$section});
print "\n";
}
print "\n";
- $lineprefix = $oldprefix;
}
sub output_enum_rst(%) {
@@ -915,6 +920,7 @@ sub output_enum_rst(%) {
my ($parameter);
my $oldprefix = $lineprefix;
my $count;
+ my $outer;
if ($sphinx_major < 3) {
my $name = "enum " . $args{'enum'};
@@ -924,14 +930,17 @@ sub output_enum_rst(%) {
print "\n\n.. c:enum:: " . $name . "\n\n";
}
print_lineno($declaration_start_line);
- $lineprefix = " ";
+ $lineprefix = " ";
output_highlight_rst($args{'purpose'});
print "\n";
- print "**Constants**\n\n";
- $lineprefix = " ";
+ print ".. container:: kernelindent\n\n";
+ $outer = $lineprefix . " ";
+ $lineprefix = $outer . " ";
+ print $outer . "**Constants**\n\n";
foreach $parameter (@{$args{'parameterlist'}}) {
- print "``$parameter``\n";
+ print $outer . "``$parameter``\n";
+
if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
output_highlight_rst($args{'parameterdescs'}{$parameter});
} else {
@@ -939,7 +948,7 @@ sub output_enum_rst(%) {
}
print "\n";
}
-
+ print "\n";
$lineprefix = $oldprefix;
output_section_rst(@_);
}
@@ -982,18 +991,19 @@ sub output_struct_rst(%) {
}
}
print_lineno($declaration_start_line);
- $lineprefix = " ";
+ $lineprefix = " ";
output_highlight_rst($args{'purpose'});
print "\n";
- print "**Definition**\n\n";
- print "::\n\n";
+ print ".. container:: kernelindent\n\n";
+ print $lineprefix . "**Definition**::\n\n";
my $declaration = $args{'definition'};
- $declaration =~ s/\t/ /g;
- print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n";
+ $lineprefix = $lineprefix . " ";
+ $declaration =~ s/\t/$lineprefix/g;
+ print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n";
- print "**Members**\n\n";
$lineprefix = " ";
+ print $lineprefix . "**Members**\n\n";
foreach $parameter (@{$args{'parameterlist'}}) {
($parameter =~ /^#/) && next;
@@ -1003,8 +1013,10 @@ sub output_struct_rst(%) {
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
$type = $args{'parametertypes'}{$parameter};
print_lineno($parameterdesc_start_lines{$parameter_name});
- print "``" . $parameter . "``\n";
+ print $lineprefix . "``" . $parameter . "``\n";
+ $lineprefix = " ";
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
+ $lineprefix = " ";
print "\n";
}
print "\n";
--
2.37.2
Em Tue, 4 Oct 2022 14:12:22 -0600
Jonathan Corbet <[email protected]> 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 <[email protected]>
> ---
> 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
Mauro Carvalho Chehab <[email protected]> writes:
> Nitpick: you forgot to close the parenthesis on your comment ;-)
Hey, I gotta provide something for people to complain about :)
>> + #
>> + 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.
The __container:: directive is pretty much defined as contributing a
<div> do the HTML output, so I do not expect problems. That said, I've
not yet tested it, and clearly need to.
> 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.
I've tested things as far back as 2.4.5, where all is well. I don't
currently have a machine that is capable of running earlier versions;
I'll need to conjure one of those up, I guess.
(Either that or just bite the bullet and move the minimum version
forward!)
Thanks,
jon
On Tue, 04 Oct 2022, Jonathan Corbet <[email protected]> wrote:
> 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.
Way back I tried to keep the formatting changes minimal to avoid opening
that particular can of worms along with the rest of the Sphinx
transition.
But I do wonder if people find value in repeating e.g. the struct
definitions in the documentation. I'd argue the rendered documentation
is more for an overview, and if you need to know the exact details,
you'll be in the editor typing code and you can look up the actual
definition in source. Having the definition feels maybe a bit excessive.
We also don't use Sphinx C Domain's ".. c:member::" for struct/union
members, or ".. c:enumerator::" for enumeration contants. They provide
arguably nicer rendering out of the box than our stuff.
The Sphinx way to do parameter lists would be field lists i.e. ":param
foo: description". Ditto for return values ":return: description". (Not
saying we should convert the comments, but kernel-doc the script could
emit those.)
Perhaps we'd be better off going towards Sphinx standard usage than
tweaking our own thing?
I'm afraid I don't have the time to work on this. Talk is cheap and all
that. My two cents.
Anyway, here are some examples how this might look like: [1].
BR,
Jani.
[1] https://hawkmoth.readthedocs.io/en/latest/examples.html
>
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> 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.
> + #
> + print ".. container:: kernelindent\n\n";
> $lineprefix = " ";
> + print $lineprefix . "**Parameters**\n\n";
> foreach $parameter (@{$args{'parameterlist'}}) {
> my $parameter_name = $parameter;
> $parameter_name =~ s/\[.*//;
> $type = $args{'parametertypes'}{$parameter};
>
> if ($type ne "") {
> - print "``$type``\n";
> + print $lineprefix . "``$type``\n";
> } else {
> - print "``$parameter``\n";
> + print $lineprefix . "``$parameter``\n";
> }
>
> print_lineno($parameterdesc_start_lines{$parameter_name});
>
> + $lineprefix = " ";
> if (defined($args{'parameterdescs'}{$parameter_name}) &&
> $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
> output_highlight_rst($args{'parameterdescs'}{$parameter_name});
> } else {
> - print " *undescribed*\n";
> + print $lineprefix . "*undescribed*\n";
> }
> + $lineprefix = " ";
> print "\n";
> }
>
> - $lineprefix = $oldprefix;
> output_section_rst(@_);
> + $lineprefix = $oldprefix;
> }
>
> sub output_section_rst(%) {
> my %args = %{$_[0]};
> my $section;
> my $oldprefix = $lineprefix;
> - $lineprefix = "";
>
> foreach $section (@{$args{'sectionlist'}}) {
> - print "**$section**\n\n";
> + print $lineprefix . "**$section**\n\n";
> print_lineno($section_start_lines{$section});
> output_highlight_rst($args{'sections'}{$section});
> print "\n";
> }
> print "\n";
> - $lineprefix = $oldprefix;
> }
>
> sub output_enum_rst(%) {
> @@ -915,6 +920,7 @@ sub output_enum_rst(%) {
> my ($parameter);
> my $oldprefix = $lineprefix;
> my $count;
> + my $outer;
>
> if ($sphinx_major < 3) {
> my $name = "enum " . $args{'enum'};
> @@ -924,14 +930,17 @@ sub output_enum_rst(%) {
> print "\n\n.. c:enum:: " . $name . "\n\n";
> }
> print_lineno($declaration_start_line);
> - $lineprefix = " ";
> + $lineprefix = " ";
> output_highlight_rst($args{'purpose'});
> print "\n";
>
> - print "**Constants**\n\n";
> - $lineprefix = " ";
> + print ".. container:: kernelindent\n\n";
> + $outer = $lineprefix . " ";
> + $lineprefix = $outer . " ";
> + print $outer . "**Constants**\n\n";
> foreach $parameter (@{$args{'parameterlist'}}) {
> - print "``$parameter``\n";
> + print $outer . "``$parameter``\n";
> +
> if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
> output_highlight_rst($args{'parameterdescs'}{$parameter});
> } else {
> @@ -939,7 +948,7 @@ sub output_enum_rst(%) {
> }
> print "\n";
> }
> -
> + print "\n";
> $lineprefix = $oldprefix;
> output_section_rst(@_);
> }
> @@ -982,18 +991,19 @@ sub output_struct_rst(%) {
> }
> }
> print_lineno($declaration_start_line);
> - $lineprefix = " ";
> + $lineprefix = " ";
> output_highlight_rst($args{'purpose'});
> print "\n";
>
> - print "**Definition**\n\n";
> - print "::\n\n";
> + print ".. container:: kernelindent\n\n";
> + print $lineprefix . "**Definition**::\n\n";
> my $declaration = $args{'definition'};
> - $declaration =~ s/\t/ /g;
> - print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n";
> + $lineprefix = $lineprefix . " ";
> + $declaration =~ s/\t/$lineprefix/g;
> + print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n";
>
> - print "**Members**\n\n";
> $lineprefix = " ";
> + print $lineprefix . "**Members**\n\n";
> foreach $parameter (@{$args{'parameterlist'}}) {
> ($parameter =~ /^#/) && next;
>
> @@ -1003,8 +1013,10 @@ sub output_struct_rst(%) {
> ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
> $type = $args{'parametertypes'}{$parameter};
> print_lineno($parameterdesc_start_lines{$parameter_name});
> - print "``" . $parameter . "``\n";
> + print $lineprefix . "``" . $parameter . "``\n";
> + $lineprefix = " ";
> output_highlight_rst($args{'parameterdescs'}{$parameter_name});
> + $lineprefix = " ";
> print "\n";
> }
> print "\n";
--
Jani Nikula, Intel Open Source Graphics Center
Em Wed, 05 Oct 2022 09:29:45 -0600
Jonathan Corbet <[email protected]> escreveu:
> Mauro Carvalho Chehab <[email protected]> writes:
> > 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.
>
> I've tested things as far back as 2.4.5, where all is well. I don't
> currently have a machine that is capable of running earlier versions;
> I'll need to conjure one of those up, I guess.
>
> (Either that or just bite the bullet and move the minimum version
> forward!)
I would just set 2.4.4 as the minimal version. This is already
the minimal version for PDF output anyway:
my $rec_version = "1.7.9"; # PDF won't build here
my $min_pdf_version = "2.4.4"; # Min version where pdf builds
and requirements.txt also sets to it. Yet, it would be nice to
change requirements to 2.4.5 as the default pip-installed version.
Regards,
Mauro
Em Wed, 05 Oct 2022 19:58:39 +0300
Jani Nikula <[email protected]> escreveu:
> On Tue, 04 Oct 2022, Jonathan Corbet <[email protected]> wrote:
> > 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.
>
> Way back I tried to keep the formatting changes minimal to avoid opening
> that particular can of worms along with the rest of the Sphinx
> transition.
>
> But I do wonder if people find value in repeating e.g. the struct
> definitions in the documentation. I'd argue the rendered documentation
> is more for an overview, and if you need to know the exact details,
> you'll be in the editor typing code and you can look up the actual
> definition in source. Having the definition feels maybe a bit excessive.
I have split thoughts regards to it. The advantage of having the
struct definition there is to allow checking the type of each argument,
which is useful. It also provide a way to double-check if the parser
is dealing well with the argument, but, on the counter-side, the
type printed by kernel-doc may not be identical to what's inside the
Kernel, on some special cases, as the parse logic for arguments is
complex. The same applies on functions and macros.
>
> We also don't use Sphinx C Domain's ".. c:member::" for struct/union
> members,
I'm wondering how much extra build time this would impact ;-)
If the impact is not huge, I'm in favor of using it.
> or ".. c:enumerator::" for enumeration contants.
This one can be more problematic, as it could break existing
cross-references.
> They provide arguably nicer rendering out of the box than our stuff.
Agreed.
> The Sphinx way to do parameter lists would be field lists i.e. ":param
> foo: description". Ditto for return values ":return: description". (Not
> saying we should convert the comments, but kernel-doc the script could
> emit those.)
>
> Perhaps we'd be better off going towards Sphinx standard usage than
> tweaking our own thing?
>
> I'm afraid I don't have the time to work on this. Talk is cheap and all
> that. My two cents.
>
> Anyway, here are some examples how this might look like: [1].
>
>
> BR,
> Jani.
>
>
>
> [1] https://hawkmoth.readthedocs.io/en/latest/examples.html
It reminds that we're currently lacking a way to describe non-macro
#defines. In special for bit-based defines, it would be nice to have
a good way to document them, without needing to convert defines into
enums.
Regards,
Mauro
On Thu, 06 Oct 2022, Mauro Carvalho Chehab <[email protected]> wrote:
> Em Wed, 05 Oct 2022 19:58:39 +0300
> Jani Nikula <[email protected]> escreveu:
>
>> On Tue, 04 Oct 2022, Jonathan Corbet <[email protected]> wrote:
>> > 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.
>>
>> Way back I tried to keep the formatting changes minimal to avoid opening
>> that particular can of worms along with the rest of the Sphinx
>> transition.
>>
>> But I do wonder if people find value in repeating e.g. the struct
>> definitions in the documentation. I'd argue the rendered documentation
>> is more for an overview, and if you need to know the exact details,
>> you'll be in the editor typing code and you can look up the actual
>> definition in source. Having the definition feels maybe a bit excessive.
>
> I have split thoughts regards to it. The advantage of having the
> struct definition there is to allow checking the type of each argument,
> which is useful. It also provide a way to double-check if the parser
> is dealing well with the argument, but, on the counter-side, the
> type printed by kernel-doc may not be identical to what's inside the
> Kernel, on some special cases, as the parse logic for arguments is
> complex. The same applies on functions and macros.
Two alternatives to removing it come to mind:
- Generating links to git.kernel.org at right version, file and line.
- A collapsible (and collapsed by default) code box. I think this needs
html/css hacking, not possible in Sphinx out of the box.
>>
>> We also don't use Sphinx C Domain's ".. c:member::" for struct/union
>> members,
>
> I'm wondering how much extra build time this would impact ;-)
> If the impact is not huge, I'm in favor of using it.
>
>> or ".. c:enumerator::" for enumeration contants.
>
> This one can be more problematic, as it could break existing
> cross-references.
Certainly.
>
>> They provide arguably nicer rendering out of the box than our stuff.
>
> Agreed.
>
>> The Sphinx way to do parameter lists would be field lists i.e. ":param
>> foo: description". Ditto for return values ":return: description". (Not
>> saying we should convert the comments, but kernel-doc the script could
>> emit those.)
>>
>> Perhaps we'd be better off going towards Sphinx standard usage than
>> tweaking our own thing?
>>
>> I'm afraid I don't have the time to work on this. Talk is cheap and all
>> that. My two cents.
>>
>> Anyway, here are some examples how this might look like: [1].
>>
>>
>> BR,
>> Jani.
>>
>>
>>
>> [1] https://hawkmoth.readthedocs.io/en/latest/examples.html
>
> It reminds that we're currently lacking a way to describe non-macro
> #defines. In special for bit-based defines, it would be nice to have
> a good way to document them, without needing to convert defines into
> enums.
ITYM simple or non-function-like macros. Sphinx supports ".. macro::"
for that nowadays, but don't know since what version. That's what I use
in Hawkmoth, and ".. function::" for macros with args.
BR,
Jani.
>
> Regards,
> Mauro
--
Jani Nikula, Intel Open Source Graphics Center
Mauro Carvalho Chehab <[email protected]> writes:
> 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.
So as far as I can tell, the PDF output is entirely unaffected. I have
not read it all, though! Is there a place in particular that you know
to be problematic where I should look?
Thanks,
jon