Em Thu, 13 Apr 2017 18:25:12 +0200
Markus Heiser <markus.hei...@darmarit.de> escreveu:
> Am 13.04.2017 um 15:29 schrieb Mauro Carvalho Chehab
> <mche...@s-opensource.com>:
>
> > Em Thu, 13 Apr 2017 14:55:03 +0200
> > Markus Heiser <markus.hei...@darmarit.de> escreveu:
> >
> >> On 13.04.2017 12:42, Mauro Carvalho Chehab wrote:
> >>> The default recursion limit is not good enough to handle
> >>> complex books. I'm sometimes receiving this error message:
> >>>
> >>> sphinx.errors.SphinxParallelError: RecursionError: maximum recursion
> >>> depth exceeded while pickling an object
> >>>
> >>> or those:
> >>>
> >>> maximum recursion depth exceeded while calling a Python object
> >>> This can happen with very large or deeply nested source files. You can
> >>> carefully increase the default Python recursion limit of 1000 in conf.py
> >>> with e.g.:
> >>> import sys; sys.setrecursionlimit(1500)
> >>>
> >>
> >> Is this behavior reproducible?
> >
> > I noticed the issue when building the docs with Sphinx 1.4.9 with
> > my ABI patches, after adding xref links to it.
> >
> > What I suspect is that Sphinx use some sort of fragile recursion
> > algorithm to parse cross references.
>
> Or the the generated refs are absurd ;)
>
> I haven't found the technical problem in detail, but I made some
> test and this is what I observed; Sometimes even a "clean":
>
> make DOCBOOKS= clean htmldocs
>
> fails with recursion error. I also realized that this behavior
> is only about the generated ABI docs. So I looked at what the
> Perl script generates:
>
> ./scripts/get_abi.pl rest --dir Documentation/ABI/testing
>
> It generates horrible titles, containing more than 4000 characters!
> I mean titles like the one shown in "<SNIP/SNAP: title>" below.
> Which ends in HTML links like the one below.
>
> OK, we can discuss why Sphinx have problems handling such titles
> and refs but:
>
> at this point I stop digging any deeper ;)
>
> IMO: this is not the way, we can include ABI into the reST doc
The problem is that a few ABI files define a single description
for a lot of different symbols. That's true, for example on
this ABI file:
Documentation/ABI/testing/sysfs-bus-iio
One alternative is to replace the titles by a table, like
what the attached patch does.
IMHO, the result looks OK:
https://mchehab.fedorapeople.org/kernel_docs/admin-guide/abi.html
I added it to my development tree:
https://git.linuxtv.org//mchehab/experimental.git/log/?h=abi_docs_v3
With this change, I removed the setrecursionlimit() call and did a
clean build. It worked fine. So, perhaps it solved the issue.
Regards,
Mauro
---
scripts/get_abi.pl: represent what in tables
Several entries at the ABI have multiple What: with the same
description.
Instead of showing those symbols as sections, let's show them
as tables. That makes easier to read on the final output,
and avoid too much recursion at Sphinx parsing.
We need to put file references at the end, as we don't want
non-file tables to be mangled with other entries.
Signed-off-by: Mauro Carvalho Chehab <mche...@s-opensource.com>
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index eb62385630e6..7856d5db44d1 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -193,16 +193,19 @@ sub parse_abi {
#
# Outputs the book on ReST format
#
+
sub output_rest {
- foreach my $what (sort keys %data) {
+ foreach my $what (sort {
+ ($data{$a}->{type} eq "File") cmp
($data{$b}->{type} eq "File") ||
+ $a cmp $b
+ } keys %data) {
my $type = $data{$what}->{type};
my $file = $data{$what}->{file};
+ my $filepath = $data{$what}->{filepath};
my $w = $what;
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
- my $bar = $w;
- $bar =~ s/./-/g;
foreach my $p (@{$data{$what}->{label}}) {
my ($content, $label) = @{$p};
@@ -222,9 +225,37 @@ sub output_rest {
last;
}
- print "$w\n$bar\n\n";
- print "- defined on file $file (type: $type)\n\n" if ($type ne
"File");
+ $filepath =~ s,.*/(.*/.*),\1,;;
+ $filepath =~ s,[/\-],_,g;;
+ my $fileref = "abi_file_".$filepath;
+
+ if ($type eq "File") {
+ my $bar = $w;
+ $bar =~ s/./-/g;
+
+ print ".. _$fileref:\n\n";
+ print "$w\n$bar\n\n";
+ } else {
+ my @names = split /\s*,\s*/,$w;
+
+ my $len = 0;
+
+ foreach my $name (@names) {
+ $len = length($name) if (length($name) > $len);
+ }
+
+ print "What:\n\n";
+
+ print "+-" . "-" x $len . "-+\n";
+ foreach my $name (@names) {
+ printf "| %s", $name . " " x ($len -
length($name)) . " |\n";
+ print "+-" . "-" x $len . "-+\n";
+ }
+ print "\n";
+ }
+
+ print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type
ne "File");
my $desc = $data{$what}->{description};
$desc =~ s/^\s+//;
--
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
