linux-kernel - Re: [PATCH] Documentation: Add a source tree map overview

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <6459566b-bf9f-4e07-9290-41853cdee9ec@infradead.org>
Date: Sun, 1 Jun 2025 19:49:08 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Bagas Sanjaya <bagasdotme@...il.com>, William Raezer <wraezer@...il.com>,
 linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org, corbet@....net
Subject: Re: [PATCH] Documentation: Add a source tree map overview



On 6/1/25 6:26 PM, Bagas Sanjaya wrote:
> On Sun, Jun 01, 2025 at 09:50:14AM -0700, Randy Dunlap wrote:
>> Hi,
>>
>> On 6/1/25 9:22 AM, William Raezer wrote:
>>> Hello,
>>>
>>
>> Please wrap email lines at around 72-75 characters each.
>>
>>> My name is William Raezer, and this is my first contribution to the Linux kernel. I'm submitting a simple but hopefully helpful addition: a high-level map of the Linux kernel source tree as a new document in `Documentation/source-map.rst`.
>>
>> This looks somewhat useful, although I was expecting more of a graphic presentation
>> of the tree structure. But that would cause trouble with the role of each subdirectory.
>> (and one can always use `tree` for that)
> 
> I was expecting tree output either.
> 
>>
>>> As someone beginning to explore the internals of the Linux kernel, I noticed that while there is some documentation available that describes the subsystems in principle, there's no centralized overview of the source tree structure itself. This patch adds a basic source map that describes the role of each top-level directory in the kernel source.
>>>
>>> The goal is to assist both myself and others in navigating the codebase, especially new contributors who may be overwhelmed by the kernel's size and complexity. As a follow-up, I plan to add subsystem-level maps for key directories such as `kernel/`, `mm/`, and `fs/`.
>>>
>>> I hope this addition is seen as a positive and useful step, and I’m open to feedback or suggestions to improve it.
>>
>> Patches should generally be inline as email text, not as attachments.
>> This is up to the maintainer to decide about...
>> and gmail is not good as maintaining whitespace in emails.
>> (I don't see any whitespace problems in the current patch.)
> 
> tl;dr: see Documentation/process/submitting-patches.rst.
> 
>>
>> I get a warning when building with this patch applied:
>>
>> Documentation/source-map.rst: WARNING: document isn't included in any toctree [toc.not_included]
> 
> make htmldocs.
> 
>>
>> Also, when I look at source-map.html with a web browser, no parts of
>> the source-map are shown. (tested with multiple browsers)

No, I mean that what I see is mostly a blank/empty page.
Other that the sidebar, it only contains this line:

©The kernel development community. | Powered by Sphinx 8.2.3 & Alabaster 1.0.0 | Page source


-- 
~Randy