lkml.org 
[lkml]   [2023]   [Nov]   [28]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH] docs: Raise the minimum Sphinx requirement to 2.4.4
Em Tue, 28 Nov 2023 07:42:12 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab@kernel.org> writes:
>
> > Em Mon, 27 Nov 2023 16:31:39 -0700
> > Jonathan Corbet <corbet@lwn.net> escreveu:
>
> >> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
> >> index 1fb88fdceec3..db75b1b86086 100755
> >> --- a/scripts/sphinx-pre-install
> >> +++ b/scripts/sphinx-pre-install
> >> @@ -32,8 +32,7 @@ my $python_cmd = "";
> >> my $activate_cmd;
> >> my $min_version;
> >> my $cur_version;
> >> -my $rec_version = "1.7.9"; # PDF won't build here
> >> -my $min_pdf_version = "2.4.4"; # Min version where pdf builds
> >> +my $rec_version = "3.0";
> >
> > Please don't. 3.0 version has a broken C domain, not properly supported.
> > The fixes arrived only starting at 3.1 (I guess some went to 3.2, but
> > 3.1 is usable, as far as I remember).
>
> So you're asking for 3.1 or 3.2 instead of 3.0?

Yes.

>
> Honestly, I just picked 3.0 out of the air in the hopes of eventually
> deprecating 2.x. Not lots of thought has gone into that
> number...perhaps we should recommend higher yet?

Well, we could recommend a higher version, but I can't see much
differences between 3.2 and the latest version: for what we use,
both will work on a similar way. Ok, layout may be different, there
were some improvements on PDF output, etc. but they will all produce
a decent documentation.

Yet, while most C domain bugs introduced on 3.0 were solved in 3.1
and 3.2, there's one still pending issue[1].

Once C domain finally gets rid from this long term bug that having:

.. c:struct:: foo

.. c:function:: void foo(void)

Produce warnings that "foo" id duplicated, then we'll have, IMO,
our next recommended version :-)

While Sphinx developers don't fix such bug, it doesn't really matter
what version user will pick, so I would just pick the fastest one
as a recommendation, starting from 3.1 or 3.2 as our currently
recommended version.

[1] https://github.com/sphinx-doc/sphinx/pull/8313

While I didn't make any benchmarks, I remember people reported
poor performance with newer versions, so, without thinking to
much, 3.1 or 3.2 seems a good candidate for the recommended
version.

Regards,
Mauro

\
 
 \ /
  Last update: 2023-11-28 16:57    [W:0.113 / U:0.096 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site