| Message ID | cover.1581955849.git.mchehab+huawei@kernel.org (mailing list archive) |
|---|---|
| Headers | show |
| Series | Manually convert filesystem FS documents to ReST | expand |
On Mon, Feb 17, 2020 at 05:11:46PM +0100, Mauro Carvalho Chehab wrote: > There are lots of plain text documents under Documentation/filesystems. > > Manually convert several of those to ReST and add them to the index file. I think at least 90% of this material needs to be in admin-guide. Should we create Documentation/admin-guide/filesystems/ and move most of these files there?
Em Mon, 17 Feb 2020 20:01:46 -0800 Matthew Wilcox <willy@infradead.org> escreveu: > On Mon, Feb 17, 2020 at 05:11:46PM +0100, Mauro Carvalho Chehab wrote: > > There are lots of plain text documents under Documentation/filesystems. > > > > Manually convert several of those to ReST and add them to the index file. > > I think at least 90% of this material needs to be in admin-guide. Should > we create Documentation/admin-guide/filesystems/ and move most of these > files there? It makes sense to me. Yet, there are some of those files that contains both user-facing and kernel-facing docs at the same place. Btw, I found the same pattern on *several* other subsystems: when someone is documenting some feature, it tends to document both kAPI, uAPI and admin. Right now, what we did so far on most places were to keep the stuff together, as splitting them could sometimes be painful. As we are too close to finish the ReST conversion[1], I would prefer to first finish it. Then, do a second pass at files outside the new directories (like admin-guide), in order to better organize things, eventually splitting some files into kAPI, uAPI and/or admin-guide. [1] Looking at next-20200217, after my last doc patches applied on this tree: https://urldefense.com/v3/__https://git.linuxtv.org/mchehab/experimental.git/log/?h=all_docs_merged__;!!GqivPVa7Brio!PN17iKHJ9Upo42OevdJbg0MsoPoDzjKk42i88P-Eeph6Y9GmY9gBs_HXyiyhltIy5GV3Fw$ excluding (most) false positives, we have now only ~50 text files left to convert: $ dirname $(find Documentation/ -type f|grep -vE '\.(rst|svg|dot|py|awk|sh|pl|gitignore|S|yaml|c|inf|vim|modes)'|grep -vE '(Makefile|Kconfig|LICENSE|COPYING-logo|ChangeLog|CREDITS)'|grep -v devicetree/bindings|grep -vE 'Documentation/(ABI|features|output|SubmittingPatches|CodingStyle|logo.gif|dontdiff|sphinx/requirements.txt|admin-guide/kdump/gdbmacros.txt|admin-guide/aoe/udev.txt|EDID/hex|netlabel/draft-ietf-cipso-ipsecurity-01.txt|firmware_class/hotplug-script|target/target-export-device|networking/mac80211-auth-assoc-deauth.txt|sparc/oradax/dax-hv-api.txt)'|grep -v translations)|sort|uniq -c|sort -n $ echo -n "Total: " $ dirname $(find Documentation/ -type f|grep -vE '\.(rst|svg|dot|py|awk|sh|pl|gitignore|S|yaml|c|inf|vim|modes)'|grep -vE '(Makefile|Kconfig|LICENSE|COPYING-logo|ChangeLog|CREDITS)'|grep -v devicetree/bindings|grep -vE 'Documentation/(ABI|features|output|SubmittingPatches|CodingStyle|logo.gif|dontdiff|sphinx/requirements.txt|admin-guide/kdump/gdbmacros.txt|admin-guide/aoe/udev.txt|EDID/hex|netlabel/draft-ietf-cipso-ipsecurity-01.txt|firmware_class/hotplug-script|target/target-export-device|networking/mac80211-auth-assoc-deauth.txt|sparc/oradax/dax-hv-api.txt)'|grep -v translations)|wc -l 1 Documentation/filesystems/cifs 1 Documentation/filesystems/configfs 1 Documentation/scsi 1 Documentation/virt/kvm/devices 2 Documentation/admin-guide 3 Documentation 6 Documentation/devicetree 6 Documentation/filesystems/caching 8 Documentation/RCU 21 Documentation/filesystems Total: 50 Once we get this series merged, I'm planning to prepare and submit a second series doing the conversion for the other ~20 filesystem files. Btw, if you want to look how things will become after my patch series, I'm keeping a html build after all my patch series at: https://urldefense.com/v3/__https://www.infradead.org/*mchehab/kernel_docs/__;fg!!GqivPVa7Brio!PN17iKHJ9Upo42OevdJbg0MsoPoDzjKk42i88P-Eeph6Y9GmY9gBs_HXyiyhltL51oe3qA$ Cheers, Mauro
On Tue, 18 Feb 2020 11:04:06 +0100 Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > Then, do a second pass at files outside the new directories (like > admin-guide), in order to better organize things, eventually splitting > some files into kAPI, uAPI and/or admin-guide. I'm looking forward to this phase! Yes it is harder, and it often requires selling the idea to skeptical maintainers. But that is how, IMO, we get from where we're at now to something closer to a set of coherent kernel docs. Thanks, jon
Em Wed, 19 Feb 2020 02:32:34 -0700 Jonathan Corbet <corbet@lwn.net> escreveu: > On Tue, 18 Feb 2020 11:04:06 +0100 > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > > > Then, do a second pass at files outside the new directories (like > > admin-guide), in order to better organize things, eventually splitting > > some files into kAPI, uAPI and/or admin-guide. > > I'm looking forward to this phase! Yes it is harder, and it often > requires selling the idea to skeptical maintainers. But that is how, > IMO, we get from where we're at now to something closer to a set of > coherent kernel docs. Yeah, fully agreed that this is an important step. I'm even more anxious for a third phase: filling the gaps. I'm pretty sure that several important parts of the Kernel aren't properly represented at Documentation. Yet, before start writing new things, we should first organizing what we already have, making them well-organized. Cheers, Mauro
On Mon, 17 Feb 2020 17:11:46 +0100 Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote: > There are lots of plain text documents under Documentation/filesystems. > > Manually convert several of those to ReST and add them to the index file. OK, I've finally managed to add all the acks and wrestle this pile into docs-next - thanks. jon
There are lots of plain text documents under Documentation/filesystems. Manually convert several of those to ReST and add them to the index file. Mauro Carvalho Chehab (44): docs: filesystems: convert 9p.txt to ReST docs: filesystems: convert adfs.txt to ReST docs: filesystems: convert affs.txt to ReST docs: filesystems: convert afs.txt to ReST docs: filesystems: convert autofs-mount-control.txt to ReST docs: filesystems: convert befs.txt to ReST docs: filesystems: convert bfs.txt to ReST docs: filesystems: convert btrfs.txt to ReST docs: filesystems: convert ceph.txt to ReST docs: filesystems: convert cramfs.txt to ReST docs: filesystems: convert debugfs.txt to ReST docs: filesystems: convert dlmfs.txt to ReST docs: filesystems: convert ecryptfs.txt to ReST docs: filesystems: convert efivarfs.txt to ReST docs: filesystems: convert erofs.txt to ReST docs: filesystems: convert ext2.txt to ReST docs: filesystems: convert ext3.txt to ReST docs: filesystems: convert f2fs.txt to ReST docs: filesystems: convert gfs2.txt to ReST docs: filesystems: convert gfs2-uevents.txt to ReST docs: filesystems: convert hfsplus.txt to ReST docs: filesystems: convert hfs.txt to ReST docs: filesystems: convert hpfs.txt to ReST docs: filesystems: convert inotify.txt to ReST docs: filesystems: convert isofs.txt to ReST docs: filesystems: convert nilfs2.txt to ReST docs: filesystems: convert ntfs.txt to ReST docs: filesystems: convert ocfs2-online-filecheck.txt to ReST docs: filesystems: convert ocfs2.txt to ReST docs: filesystems: convert omfs.txt to ReST docs: filesystems: convert orangefs.txt to ReST docs: filesystems: convert proc.txt to ReST docs: filesystems: convert qnx6.txt to ReST docs: filesystems: convert ramfs-rootfs-initramfs.txt to ReST docs: filesystems: convert relay.txt to ReST docs: filesystems: convert romfs.txt to ReST docs: filesystems: convert squashfs.txt to ReST docs: filesystems: convert sysfs.txt to ReST docs: filesystems: convert sysv-fs.txt to ReST docs: filesystems: convert tmpfs.txt to ReST docs: filesystems: convert ubifs-authentication.rst.txt to ReST docs: filesystems: convert ubifs.txt to ReST docs: filesystems: convert udf.txt to ReST docs: filesystems: convert zonefs.txt to ReST Documentation/filesystems/{9p.txt => 9p.rst} | 114 +- .../filesystems/{adfs.txt => adfs.rst} | 29 +- .../filesystems/{affs.txt => affs.rst} | 62 +- .../filesystems/{afs.txt => afs.rst} | 73 +- ...t-control.txt => autofs-mount-control.rst} | 102 +- .../filesystems/{befs.txt => befs.rst} | 59 +- .../filesystems/{bfs.txt => bfs.rst} | 37 +- .../filesystems/{btrfs.txt => btrfs.rst} | 3 + .../filesystems/{ceph.txt => ceph.rst} | 26 +- .../filesystems/{cramfs.txt => cramfs.rst} | 19 +- .../filesystems/{debugfs.txt => debugfs.rst} | 54 +- .../filesystems/{dlmfs.txt => dlmfs.rst} | 28 +- .../{ecryptfs.txt => ecryptfs.rst} | 44 +- .../{efivarfs.txt => efivarfs.rst} | 5 +- .../filesystems/{erofs.txt => erofs.rst} | 175 +- .../filesystems/{ext2.txt => ext2.rst} | 41 +- .../filesystems/{ext3.txt => ext3.rst} | 2 + .../filesystems/{f2fs.txt => f2fs.rst} | 252 +-- .../{gfs2-uevents.txt => gfs2-uevents.rst} | 20 +- .../filesystems/{gfs2.txt => gfs2.rst} | 20 +- .../filesystems/{hfs.txt => hfs.rst} | 23 +- .../filesystems/{hfsplus.txt => hfsplus.rst} | 2 + .../filesystems/{hpfs.txt => hpfs.rst} | 239 ++- Documentation/filesystems/index.rst | 46 +- .../filesystems/{inotify.txt => inotify.rst} | 33 +- Documentation/filesystems/isofs.rst | 64 + Documentation/filesystems/isofs.txt | 48 - .../filesystems/{nilfs2.txt => nilfs2.rst} | 40 +- .../filesystems/{ntfs.txt => ntfs.rst} | 143 +- ...lecheck.txt => ocfs2-online-filecheck.rst} | 45 +- .../filesystems/{ocfs2.txt => ocfs2.rst} | 31 +- Documentation/filesystems/omfs.rst | 112 ++ Documentation/filesystems/omfs.txt | 106 -- .../{orangefs.txt => orangefs.rst} | 187 +- .../filesystems/{proc.txt => proc.rst} | 1498 +++++++++-------- .../filesystems/{qnx6.txt => qnx6.rst} | 22 + ...itramfs.txt => ramfs-rootfs-initramfs.rst} | 54 +- .../filesystems/{relay.txt => relay.rst} | 129 +- .../filesystems/{romfs.txt => romfs.rst} | 42 +- .../{squashfs.txt => squashfs.rst} | 60 +- .../filesystems/{sysfs.txt => sysfs.rst} | 324 ++-- .../filesystems/{sysv-fs.txt => sysv-fs.rst} | 155 +- .../filesystems/{tmpfs.txt => tmpfs.rst} | 44 +- .../filesystems/ubifs-authentication.rst | 10 +- .../filesystems/{ubifs.txt => ubifs.rst} | 25 +- .../filesystems/{udf.txt => udf.rst} | 21 +- .../filesystems/{zonefs.txt => zonefs.rst} | 106 +- 47 files changed, 2739 insertions(+), 2035 deletions(-) rename Documentation/filesystems/{9p.txt => 9p.rst} (63%) rename Documentation/filesystems/{adfs.txt => adfs.rst} (85%) rename Documentation/filesystems/{affs.txt => affs.rst} (86%) rename Documentation/filesystems/{afs.txt => afs.rst} (90%) rename Documentation/filesystems/{autofs-mount-control.txt => autofs-mount-control.rst} (89%) rename Documentation/filesystems/{befs.txt => befs.rst} (83%) rename Documentation/filesystems/{bfs.txt => bfs.rst} (71%) rename Documentation/filesystems/{btrfs.txt => btrfs.rst} (96%) rename Documentation/filesystems/{ceph.txt => ceph.rst} (91%) rename Documentation/filesystems/{cramfs.txt => cramfs.rst} (88%) rename Documentation/filesystems/{debugfs.txt => debugfs.rst} (91%) rename Documentation/filesystems/{dlmfs.txt => dlmfs.rst} (86%) rename Documentation/filesystems/{ecryptfs.txt => ecryptfs.rst} (70%) rename Documentation/filesystems/{efivarfs.txt => efivarfs.rst} (85%) rename Documentation/filesystems/{erofs.txt => erofs.rst} (54%) rename Documentation/filesystems/{ext2.txt => ext2.rst} (91%) rename Documentation/filesystems/{ext3.txt => ext3.rst} (88%) rename Documentation/filesystems/{f2fs.txt => f2fs.rst} (84%) rename Documentation/filesystems/{gfs2-uevents.txt => gfs2-uevents.rst} (94%) rename Documentation/filesystems/{gfs2.txt => gfs2.rst} (76%) rename Documentation/filesystems/{hfs.txt => hfs.rst} (80%) rename Documentation/filesystems/{hfsplus.txt => hfsplus.rst} (95%) rename Documentation/filesystems/{hpfs.txt => hpfs.rst} (66%) rename Documentation/filesystems/{inotify.txt => inotify.rst} (83%) create mode 100644 Documentation/filesystems/isofs.rst delete mode 100644 Documentation/filesystems/isofs.txt rename Documentation/filesystems/{nilfs2.txt => nilfs2.rst} (89%) rename Documentation/filesystems/{ntfs.txt => ntfs.rst} (85%) rename Documentation/filesystems/{ocfs2-online-filecheck.txt => ocfs2-online-filecheck.rst} (77%) rename Documentation/filesystems/{ocfs2.txt => ocfs2.rst} (88%) create mode 100644 Documentation/filesystems/omfs.rst delete mode 100644 Documentation/filesystems/omfs.txt rename Documentation/filesystems/{orangefs.txt => orangefs.rst} (83%) rename Documentation/filesystems/{proc.txt => proc.rst} (65%) rename Documentation/filesystems/{qnx6.txt => qnx6.rst} (98%) rename Documentation/filesystems/{ramfs-rootfs-initramfs.txt => ramfs-rootfs-initramfs.rst} (91%) rename Documentation/filesystems/{relay.txt => relay.rst} (91%) rename Documentation/filesystems/{romfs.txt => romfs.rst} (86%) rename Documentation/filesystems/{squashfs.txt => squashfs.rst} (91%) rename Documentation/filesystems/{sysfs.txt => sysfs.rst} (56%) rename Documentation/filesystems/{sysv-fs.txt => sysv-fs.rst} (73%) rename Documentation/filesystems/{tmpfs.txt => tmpfs.rst} (86%) rename Documentation/filesystems/{ubifs.txt => ubifs.rst} (91%) rename Documentation/filesystems/{udf.txt => udf.rst} (83%) rename Documentation/filesystems/{zonefs.txt => zonefs.rst} (90%)