Re: Sphinx version dependencies?

["Darrick J. Wong" <darrick.wong@oracle.com>]

On Thu, Jul 19, 2018 at 02:15:56PM -0400, Theodore Y. Ts'o wrote:
> Darrick has sent in patches to convert the ext4 documentation to use
> rst and to be built as part of the full kernel documentation thanks.
> In addition to that, he's imported the on-disk documentation from the
> ext4 wiki into the kernel sources, so hopefully we can keep it more up
> to date.
> 
> When I was experimenting with this, I had to actually build the kernel
> docs using Sphinx for the first time.  I'm using Debian testing, so at
> first I blindly followed the instructions by
> ./scripts/sphinx-pre-install:
> 
> Detected OS: Debian GNU/Linux unstable (sid).
> 	/usr/local/bin/virtualenv sphinx_1.4
> 	. sphinx_1.4/bin/activate
> 	pip install -r Documentation/sphinx/requirements.txt
> 
> But when I did that, Sphinx had heartburn over the ext4.rst file.
> 
>     ./include/linux/spi/spi.h:373: ERROR: Unexpected indentation.
>     /usr/projects/linux/ext4/Documentation/filesystems/ext4/ext4.rst:139: ERROR: Malformed table.
>     Column span alignment problem in table line 5.

Hmmm, apparently it's choking on the table heading borders not matching
the text:

====== ===========
Foo    Bar
====== ===========        <-- need to extend to EOL
Blah   Blah blah blah blah
====== ===========

Though weirdly while I /can/ get this error to reproduce with the
virtualenv 1.4.9 release, I can't get it to reproduce with the 1.3.6 or
1.6.7 ubuntu packages.  Maybe it's a python3 thing, maybe not?  Seems
pretty fragile to me.

Anyway, I'll fix ext4.rst and resubmit that part to get this moving.

--D

>     ...
> 
> After consulting with Darrick, it appears the problem is that Sphinx8
> 1.4.9 was the problem.  This is the version that
> Documentation/sphinx/requirements.txt calls for.  He did his rst
> conversion work using Ubuntu 18.04's Sphinx 1.6.7.
> 
> As it turns out Debian testing/unstable already has Sphinx 1.7.5 in
> its repository, so if I simply install Sphinx 1.7.5, it works fine.
> That's what I've done for now.
> 
> So that leaves me with some questions:
> 
> * Is there a reason why scripts/sphinx-pre-install suggested using a
>   Python virtual environment and installing Sphinx 1.4.9 instead of
>   using the distro's pre-packaged Sphinx for Debian unstable/testing?
> 
> * Why does Documentation/sphinx/requirements.txt asking for such an
>   old version of Sphinx?
>  
> * Is it a requirement that *.rst files that are checked into the
>   kernel repo have to work with Sphinx 1.4.9?  Or is it sufficient
>   that it works with Sphinx 1.6.7 and 1.7.5 (which are the prepackaged
>   Debian and Ubuntu versions).  And it looks like Fedora 28 has Sphinx
>   1.7.2 if I'm not mistaken.   How many versions of Sphinx are various
>   automated build/test systems using?
> 
> Thanks,
> 
> 						- Ted
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html