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.
...
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
