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

[Randy Dunlap]

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