Em Sat, 5 Jun 2021 12:11:09 -0300 Nícolas F. R. A. Prado <n@xxxxxxxxxxxxx> 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@xxxxxxxxxxxx/ > > > > 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
