Re: [PATCH 2/2] docs: promote the ext4 data structures book to top level
On Thu, Oct 04, 2018 at 05:59:44PM -0700, Darrick J. Wong wrote: > From: Darrick J. Wong > > Move the ext4 data structures book to Documentation/filesystems/ext4/ > since the administrative information moved elsewhere. > > Signed-off-by: Darrick J. Wong Thanks, applied and pushed out to the ext4.git tree. Randy, Jon: the original patch didn't make it past vger.kernel.org because it was too large (it was moving a lot of files around). It looked fine to me, but if you want to take a look it should be on the dev branch of the ext4.git tree. - Ted
Re: [PATCH 0/2] ext4: even more documentation fixes
On Thu, Oct 04, 2018 at 07:48:31PM -0700, Randy Dunlap wrote: > Hi Darrick, > > I don't see patch 2/2 anywhere (my inbox, email archives)... Probably because it's moving a lot of files around, so the diffs were 276k. > > -- > ~Randy
Re: [RFC PATCH 00/13] ext4: major documentation surgery
On Sat, Jul 21, 2018 at 11:19:54AM -0700, Darrick J. Wong wrote: > > I pondered that -- maybe leave all the ext4 stuff clustered together, > but link to it from the actual user/admin guide section? > Yeah, I think it makes keep the ext4 (and in the future, xfs, btrfs, f2fs, etc.) files clustered together. Is it considered OK for individual .rst files to be linked from multiple places? I could also see us wanting to change up the pdf boundaries. I doubt someone would want a single pdf with details of the VFS layer, ext4 mount options, ext4 on-disk format, xfs mount options, xfs on-disk format, btrfs mount options, etc., all in a single "book". > > I'm not sure what the best way to do that might be, but maybe some of > > the folks on the linux-doc list will have some suggestions. > > I was thinking about having a separate top-level Filesystems section > where we could put user/admin guides, on-disk documentation, etc. and > leave the FS API section alone. I wonder if part of the problem is calling it "the API section". Maybe we should be calling it Kernel Internals, or something like that? - Ted P.S. Oh, and we probably want to move "The Linux Journalling API" out of index.rst, and into a separate jbd2.rst file, and give some context that it is the journalling layer used by ext4 and ocfs2, but it's certainly not the only Journalling API in the kernel. -- 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
Re: [RFC PATCH 00/13] ext4: major documentation surgery
On Tue, Jul 10, 2018 at 10:16:42AM -0700, Darrick J. Wong wrote: > Hi all, > > This series converts the existing in-kernel ext4 documentation to rst > format, links it in with the rest of the kernel's rst documetation, and > then begins pulling in the contents of the on-disk layout page in the > wiki. No changes are made to the text during the import process except > to flatten the nested tables in the old wiki page, which were very > difficult to maintain. > > I've built the docs and put them here, in case you hate reading rst: > https://djwong.org/docs/kdoc/filesystems/ext4/index.html I've applied these patches, but I think we still need to do some work figuring out how to integrate the ext4 documentation into the Linux-doc tree as a whole. At the moment they are dropped in the middle of the "Kernel API Documentation", by virtue of where the files are located. Most of the ext4.rst file probably should be moved into the user's and administrator's guide. I'm not sure where the best place to put the ondisk documentation. It's probably not the user's and administrator's guide, but the Kernel API Documentation doesn't seem like the right place. But it should also make sense when people are browing the Documentation source directories, too. I'm not sure what the best way to do that might be, but maybe some of the folks on the linux-doc list will have some suggestions. Cheers, - Ted -- 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
Sphinx version dependencies?
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 -- 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
