Em Sat, 5 Jun 2021 12:11:09 -0300 Nícolas F. R. A. Prado n@nfraprado.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:
- when :doc: tag is used to point to a kernel-doc DOC: markup;
- 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