netdev - Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag

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 for Android: free password hash cracker in your pocket

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

Message-ID: <20210605210836.540577d4@coco.lan>
Date:   Sat, 5 Jun 2021 21:08:36 +0200
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     "Nícolas F. R. A. Prado" <n@...aprado.net>
Cc:     Jonathan Corbet <corbet@....net>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org, bpf@...r.kernel.org,
        coresight@...ts.linaro.org, devicetree@...r.kernel.org,
        kunit-dev@...glegroups.com, kvm@...r.kernel.org,
        linux-acpi@...r.kernel.org, linux-arm-kernel@...ts.infradead.org,
        linux-gpio@...r.kernel.org, linux-hwmon@...r.kernel.org,
        linux-i2c@...r.kernel.org, linux-kselftest@...r.kernel.org,
        linux-media@...r.kernel.org, linux-pci@...r.kernel.org,
        linux-pm@...r.kernel.org, linux-security-module@...r.kernel.org,
        netdev@...r.kernel.org
Subject: Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag

Em Sat, 5 Jun 2021 12:11:09 -0300
Nícolas F. R. A. Prado <n@...aprado.net> escreveu:

> Hi Mauro,
> 
> On Sat, Jun 05, 2021 at 03:17:59PM +0200, Mauro Carvalho Chehab wrote:
> > As discussed at:
> > 	https://lore.kernel.org/linux-doc/871r9k6rmy.fsf@meer.lwn.net/
> > 
> > It is better to avoid using :doc:`foo` to refer to Documentation/foo.rst, as the
> > automarkup.py extension should handle it automatically, on most cases.
> > 
> > There are a couple of exceptions to this rule:
> > 
> > 1. when :doc:  tag is used to point to a kernel-doc DOC: markup;
> > 2. when it is used with a named tag, e. g. :doc:`some name <foo>`;
> > 
> > It should also be noticed that automarkup.py has currently an issue:
> > if one use a markup like:
> > 
> > 	Documentation/dev-tools/kunit/api/test.rst
> > 	  - documents all of the standard testing API excluding mocking
> > 	    or mocking related features.
> > 
> > or, even:
> > 
> > 	Documentation/dev-tools/kunit/api/test.rst
> > 	    documents all of the standard testing API excluding mocking
> > 	    or mocking related features.
> > 	
> > The automarkup.py will simply ignore it. Not sure why. This patch series
> > avoid the above patterns (which is present only on 4 files), but it would be
> > nice to have a followup patch fixing the issue at automarkup.py.  
> 
> What I think is happening here is that we're using rST's syntax for definition
> lists [1]. automarkup.py ignores literal nodes, and perhaps a definition is
> considered a literal by Sphinx. Adding a blank line after the Documentation/...
> or removing the additional indentation makes it work, like you did in your
> 2nd and 3rd patch, since then it's not a definition anymore, although then the
> visual output is different as well.

A literal has a different output. I think that this is not the case, but I 
didn't check the python code from docutils/Sphinx.
 
> I'm not sure this is something we need to fix. Does it make sense to use
> definition lists for links like that? If it does, I guess one option would be to
> whitelist definition lists so they aren't ignored by automarkup, but I feel
> this could get ugly really quickly.

Yes, we should avoid handling literal blocks, as this can be a nightmare.

> FWIW note that it's also possible to use relative paths to docs with automarkup.

Not sure if you meant to say using something like ../driver-api/foo.rst.
If so, relative paths are a problem, as it will pass unnoticed by this script:

	./scripts/documentation-file-ref-check

which is meant to warn when a file is moved to be elsewhere. Ok, it
could be taught to use "../" to identify paths, but I suspect that this
could lead to false positives, like here:

	Documentation/usb/gadget-testing.rst:  # ln -s ../../uncompressed/u
	Documentation/usb/gadget-testing.rst:  # cd ../../class/fs
	Documentation/usb/gadget-testing.rst:  # ln -s ../../header/h

If you meant, instead, :doc:`../foo`, this series address those too.

Regards,
Mauro