Re: [PATCH v2] README: rename to README.rst and make the doc references links

[Randy Dunlap]

Hi,

On 9/21/26 12:05 AM, Osman Ahmadzai wrote:
> The README points at some sixty files in the tree, but it has no
> extension, so it shows up as plain text and none of those paths can be
> followed.  You have to go and find each one by hand.
> 
> The content has always been reStructuredText - it uses reST section
> syntax for its headings - so give it the extension to match, and wrap
> each in-tree reference in an anonymous hyperlink whose link text is the
> path itself.  The rendered text is byte-for-byte what it was before; only

What causes README.rst to be rendered? Is it named README.html?
I don't see it being rendered on a clean 'make htmldocs' build.

I see DOCS/Documentation/output/admin-guide/README.html, but that's
a different file.

> the markup is new.  Anonymous because a handful of the paths are listed
> twice and named targets would collide.
> 
> checkpatch.pl and get_maintainer.pl both test for a file called README to
> find the top of the tree, and the Makefile points readers at ./README, so
> those are updated in step.  scripts/spdxexclude lists the file as having
> no copyrightable content; only its path changes there.
> 
> Signed-off-by: Osman Ahmadzai <osmanahmadxai@xxxxxxxxx>
> ---
> v2: Dropped the second file - you are right, two copies would be out of
>     sync within a release.  This renames instead, so there is one copy of
>     the content, and updates the four places that referred to the old
>     name.  I went with the rename rather than the symlink because it
>     leaves nothing pointing at a name that no longer describes the file,
>     and the fixups turned out to be one line each.
> 
>     I did look at folding it into Documentation/index.rst, and it looks
>     like a bigger change than this one rather than an alternative to it.
>     The README names 55 documents; only 12 of them appear in the
>     index.rst toctrees today, the other 43 being reachable only by
>     descending into process/index.rst, subsystem-apis.rst and the rest.
>     So integrating means either pulling those 43 into index.rst or
>     dropping them, and that is an editorial call about material that
>     landed in b9a565b3e4d8 last November rather than a presentation fix.
>     I would rather not make it as a side effect of this patch.
> 
>     If you do want it, what I had in mind is a short "where to start"
>     section near the top of index.rst - one entry per kind of reader,
>     pointing at the existing index documents (process/index.rst for new
>     developers, subsystem-apis.rst for internals, admin-guide/index.rst
>     for administrators, and so on) rather than repeating the individual
>     paths.  Around forty lines, and automarkup turns every path in it
>     into a link with no markup needed.  The README would then shrink to a
>     pointer at the documentation.  Say the word and I will send it as its
>     own patch.
> 
>  Makefile                  |   4 +-
>  README                    | 168 -------------------------------------
>  README.rst                | 170 ++++++++++++++++++++++++++++++++++++++
>  scripts/checkpatch.pl     |   2 +-
>  scripts/get_maintainer.pl |   2 +-
>  scripts/spdxexclude       |   2 +-
>  6 files changed, 175 insertions(+), 173 deletions(-)
>  delete mode 100644 README
>  create mode 100644 README.rst

thanks.
-- 
~Randy