Re: [PATCH] docs: Remove literal markup from Documentation/ paths

[Nícolas F. R. A. Prado]

On Sat, Apr 05, 2025 at 10:17:16AM +0900, Akira Yokosawa wrote:
> Hi,
> 
> Nícolas F. R. A. Prado wrote:
> > Given that the automarkup Sphinx plugin cross-references
> > "Documentation/*.rst" strings in the text to the corresponding
> > documents, surrounding those strings with the literal markup (``) not
> > only adds unnecessary markup in the source files, but actually prevents
> > the automatic cross-referencing to happen (as it doesn't happen in
> > literal blocks).
> > 
> > Remove all the occurrences of the literal markup in
> > "Documentation/*.rst" paths, except when the actual source file is being
> > referred. Also change the surrounding text when needed so it reads well
> > both in the source and the web page (eg. 'see file Doc...' -> 'see
> > Doc...').
> > 
> > Signed-off-by: Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxx>
> > ---
[..]
> >  
> >  2) All new ``Kconfig`` options have help text.
> >  
> > @@ -47,7 +48,7 @@ Provide documentation
> >  2) All new ``/proc`` entries are documented under ``Documentation/``
> >  
> >  3) All new kernel boot parameters are documented in
> > -   ``Documentation/admin-guide/kernel-parameters.rst``.
> > +   Documentation/admin-guide/kernel-parameters.rst.
> 
> Hmm, this item is asking "Have you documented the new params in that
> particular file?", so I don't think this change should be made.

Right, that makes sense. I'll drop this and the below change for v2.

Thanks,
Nícolas

> 
> >  
> >  4) All new module parameters are documented with ``MODULE_PARM_DESC()``
> >  
> > @@ -58,7 +59,7 @@ Provide documentation
> >     linux-api@xxxxxxxxxxxxxxx.
> >  
> >  6) If any ioctl's are added by the patch, then also update
> > -   ``Documentation/userspace-api/ioctl/ioctl-number.rst``.
> > +   Documentation/userspace-api/ioctl/ioctl-number.rst.
> 
> Ditto.
> 
>         Thanks, Akira
> 
> >  
> >  Check your code with tools
> >  ==========================
>