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
