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

[Randy Dunlap]

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)

> 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.)

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]

Also, when I look at source-map.html with a web browser, no parts of
the source-map are shown. (tested with multiple browsers)

Thanks.
-- 
~Randy