From: "Nícolas F. R. A. Prado" <n@nfraprado.net> To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Cc: Jonathan Corbet <corbet@lwn.net>, Linux Doc Mailing List <linux-doc@vger.kernel.org>, linux-kernel@vger.kernel.org, bpf@vger.kernel.org, coresight@lists.linaro.org, devicetree@vger.kernel.org, kunit-dev@googlegroups.com, kvm@vger.kernel.org, linux-acpi@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-gpio@vger.kernel.org, linux-hwmon@vger.kernel.org, linux-i2c@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-media@vger.kernel.org, linux-pci@vger.kernel.org, linux-pm@vger.kernel.org, linux-security-module@vger.kernel.org, netdev@vger.kernel.org Subject: Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Date: Mon, 7 Jun 2021 21:34:58 -0300 [thread overview] Message-ID: <20210608003458.kwhbn6mraekcutlt@notapiano> (raw) In-Reply-To: <20210607093422.0a369909@coco.lan> Hi Mauro, On Mon, Jun 07, 2021 at 09:34:22AM +0200, Mauro Carvalho Chehab wrote: > Em Sun, 6 Jun 2021 19:52:25 -0300 > Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > > > On Sat, Jun 05, 2021 at 09:08:36PM +0200, Mauro Carvalho Chehab wrote: > > > 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: > > > > > > > > > > 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. > > > > Okay, I went in deeper to understand the issue and indeed it wasn't what I > > thought. The reason definitions are ignored by automarkup.py is because the main > > loop iterates only over nodes that are of type paragraph: > > > > for para in doctree.traverse(nodes.paragraph): > > for node in para.traverse(nodes.Text): > > if not isinstance(node.parent, nodes.literal): > > node.parent.replace(node, markup_refs(name, app, node)) > > > > And inspecting the HTML output from your example, the definition name is inside > > a <dt> tag, and it doesn't have a <p> inside. So in summary, automarkup.py will > > only work on elements which are inside a <p> in the output. > > > Yeah, that's what I was suspecting, based on the comments. > > Maybe something similar to the above could be done also for some > non-paragraph data. By looking at: > > https://docutils.sourceforge.io/docs/ref/doctree.html > > It says that the body elements are: > > admonition, attention, block_quote, bullet_list, caution, citation, > comment, compound, container, danger, definition_list, doctest_block, > enumerated_list, error, field_list, figure, footnote, hint, image, > important, line_block, literal_block, note, option_list, paragraph, > pending, raw, rubric, substitution_definition, system_message, > table, target, tip, warning Ok, I went through each one by searching the term on [1] and inspecting the element to see if it contained a <p> or not. The vast majority did. These are the ones I didn't find there or didn't make sense: comment container image pending raw substitution_definition system_message target We can safely ignore them. And these are the ones that matter and don't have paragraphs: 1. literal_block 2. doctest_block 3. definition_list 4. field_list 5. option_list 6. line_block 1 and 2 are literals, so we don't care about them. 3 is the one you noticed the issue with. It's worth mentioning that the definition term doesn't have a paragraph, but its definition does (as can be checked by inspecting [2]). 4 is basically the same as 3, the rst syntax is different but the output is the same. That said, I believe we only use those to set options at the top of the file, like in translations, and I can't see automarkup being useful in there. 5 is similar to 3 and 4, but the term is formatted using <kbd>, so it's like a literal and therefore not relevant. 6 is useful just to preserve indentation, and I'm pretty sure we don't use it in the docs. So in the end, I think the only contenders to be added to automarkup are definition lists, and even then I still think we should just substitute those definition lists with alternatives like you did in your patches. Personally I don't see much gain in using definitions instead of a simple paragraph. But if you really think it's an improvement in some way, it could probably be added to automarkup in the way you described. Thanks, Nícolas [1] https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html [2] https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/lists_tables.html?highlight=definition%20list#definition-lists > > So, perhaps a similar loop for definition_list would do the trick, > but maybe automarkup should also look at other types, like enum lists, > notes (and their variants, like error/warning) and footnotes. > > No idea how this would affect the docs build time, though. > > > Only applying the automarkup inside paragraphs seems like a good decision (which > > covers text in lists and tables as well), so unless there are other types of > > elements without paragraphs where automarkup should work, I think we should just > > avoid using definition lists pointing to documents like that. > > Checking the code or doing some tests are needed for us to be sure about what > of the above types docutils don't consider a paragraph. > > Thanks, > Mauro
WARNING: multiple messages have this Message-ID (diff)
From: "Nícolas F. R. A. Prado" <n@nfraprado.net> To: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Cc: Jonathan Corbet <corbet@lwn.net>, Linux Doc Mailing List <linux-doc@vger.kernel.org>, linux-kernel@vger.kernel.org, bpf@vger.kernel.org, coresight@lists.linaro.org, devicetree@vger.kernel.org, kunit-dev@googlegroups.com, kvm@vger.kernel.org, linux-acpi@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-gpio@vger.kernel.org, linux-hwmon@vger.kernel.org, linux-i2c@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-media@vger.kernel.org, linux-pci@vger.kernel.org, linux-pm@vger.kernel.org, linux-security-module@vger.kernel.org, netdev@vger.kernel.org Subject: Re: [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Date: Mon, 7 Jun 2021 21:34:58 -0300 [thread overview] Message-ID: <20210608003458.kwhbn6mraekcutlt@notapiano> (raw) In-Reply-To: <20210607093422.0a369909@coco.lan> Hi Mauro, On Mon, Jun 07, 2021 at 09:34:22AM +0200, Mauro Carvalho Chehab wrote: > Em Sun, 6 Jun 2021 19:52:25 -0300 > Nícolas F. R. A. Prado <n@nfraprado.net> escreveu: > > > On Sat, Jun 05, 2021 at 09:08:36PM +0200, Mauro Carvalho Chehab wrote: > > > 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: > > > > > > > > > > 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. > > > > Okay, I went in deeper to understand the issue and indeed it wasn't what I > > thought. The reason definitions are ignored by automarkup.py is because the main > > loop iterates only over nodes that are of type paragraph: > > > > for para in doctree.traverse(nodes.paragraph): > > for node in para.traverse(nodes.Text): > > if not isinstance(node.parent, nodes.literal): > > node.parent.replace(node, markup_refs(name, app, node)) > > > > And inspecting the HTML output from your example, the definition name is inside > > a <dt> tag, and it doesn't have a <p> inside. So in summary, automarkup.py will > > only work on elements which are inside a <p> in the output. > > > Yeah, that's what I was suspecting, based on the comments. > > Maybe something similar to the above could be done also for some > non-paragraph data. By looking at: > > https://docutils.sourceforge.io/docs/ref/doctree.html > > It says that the body elements are: > > admonition, attention, block_quote, bullet_list, caution, citation, > comment, compound, container, danger, definition_list, doctest_block, > enumerated_list, error, field_list, figure, footnote, hint, image, > important, line_block, literal_block, note, option_list, paragraph, > pending, raw, rubric, substitution_definition, system_message, > table, target, tip, warning Ok, I went through each one by searching the term on [1] and inspecting the element to see if it contained a <p> or not. The vast majority did. These are the ones I didn't find there or didn't make sense: comment container image pending raw substitution_definition system_message target We can safely ignore them. And these are the ones that matter and don't have paragraphs: 1. literal_block 2. doctest_block 3. definition_list 4. field_list 5. option_list 6. line_block 1 and 2 are literals, so we don't care about them. 3 is the one you noticed the issue with. It's worth mentioning that the definition term doesn't have a paragraph, but its definition does (as can be checked by inspecting [2]). 4 is basically the same as 3, the rst syntax is different but the output is the same. That said, I believe we only use those to set options at the top of the file, like in translations, and I can't see automarkup being useful in there. 5 is similar to 3 and 4, but the term is formatted using <kbd>, so it's like a literal and therefore not relevant. 6 is useful just to preserve indentation, and I'm pretty sure we don't use it in the docs. So in the end, I think the only contenders to be added to automarkup are definition lists, and even then I still think we should just substitute those definition lists with alternatives like you did in your patches. Personally I don't see much gain in using definitions instead of a simple paragraph. But if you really think it's an improvement in some way, it could probably be added to automarkup in the way you described. Thanks, Nícolas [1] https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html [2] https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/lists_tables.html?highlight=definition%20list#definition-lists > > So, perhaps a similar loop for definition_list would do the trick, > but maybe automarkup should also look at other types, like enum lists, > notes (and their variants, like error/warning) and footnotes. > > No idea how this would affect the docs build time, though. > > > Only applying the automarkup inside paragraphs seems like a good decision (which > > covers text in lists and tables as well), so unless there are other types of > > elements without paragraphs where automarkup should work, I think we should just > > avoid using definition lists pointing to documents like that. > > Checking the code or doing some tests are needed for us to be sure about what > of the above types docutils don't consider a paragraph. > > Thanks, > Mauro _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
next prev parent reply other threads:[~2021-06-08 0:35 UTC|newest] Thread overview: 73+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-06-05 13:17 [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab 2021-06-05 13:17 ` Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 01/34] docs: devices.rst: better reference documentation docs Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 02/34] docs: dev-tools: kunit: don't use a table for docs name Mauro Carvalho Chehab 2021-06-05 15:43 ` David Gow 2021-06-05 16:06 ` Mauro Carvalho Chehab 2021-06-07 20:14 ` Brendan Higgins 2021-06-05 13:18 ` [PATCH 03/34] media: docs: */media/index.rst: don't use ReST doc:`foo` Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 04/34] media: userspace-api: avoid using ReST :doc:`foo` markup Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 05/34] media: driver-api: drivers: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 06/34] media: admin-guide: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 07/34] docs: admin-guide: pm: avoid using ReSt " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 08/34] docs: admin-guide: hw-vuln: avoid using ReST " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 09/34] docs: admin-guide: sysctl: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 10/34] docs: block: biodoc.rst: avoid using ReSt " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 11/34] docs: bpf: bpf_lsm.rst: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 12/34] docs: core-api: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 13/34] docs: dev-tools: testing-overview.rst: " Mauro Carvalho Chehab 2021-06-05 15:43 ` David Gow 2021-06-05 16:13 ` Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 14/34] docs: dev-tools: kunit: avoid using ReST " Mauro Carvalho Chehab 2021-06-05 15:44 ` David Gow 2021-06-16 6:00 ` Mauro Carvalho Chehab 2021-06-16 6:13 ` Mauro Carvalho Chehab 2021-06-07 20:20 ` Brendan Higgins 2021-06-05 13:18 ` [PATCH 15/34] docs: devicetree: bindings: submitting-patches.rst: avoid using ReSt " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 16/34] docs: doc-guide: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 17/34] docs: driver-api: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 18/34] docs: driver-api: gpio: using-gpio.rst: " Mauro Carvalho Chehab 2021-06-05 16:25 ` Linus Walleij 2021-06-05 13:18 ` [PATCH 19/34] docs: driver-api: surface_aggregator: " Mauro Carvalho Chehab 2021-06-05 14:14 ` Maximilian Luz 2021-06-07 9:31 ` Hans de Goede 2021-06-07 9:55 ` Mauro Carvalho Chehab 2021-06-07 10:07 ` Hans de Goede 2021-06-05 13:18 ` [PATCH 20/34] docs: driver-api: usb: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 21/34] docs: firmware-guide: acpi: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 22/34] docs: hwmon: adm1177.rst: " Mauro Carvalho Chehab 2021-06-06 13:01 ` Guenter Roeck 2021-06-05 13:18 ` [PATCH 23/34] docs: i2c: " Mauro Carvalho Chehab 2021-06-05 15:13 ` Wolfram Sang 2021-06-05 13:18 ` [PATCH 24/34] docs: kernel-hacking: hacking.rst: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 25/34] docs: networking: devlink: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 26/34] docs: PCI: endpoint: pci-endpoint-cfs.rst: " Mauro Carvalho Chehab 2021-06-10 23:46 ` Bjorn Helgaas 2021-06-11 8:45 ` Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 27/34] docs: PCI: pci.rst: " Mauro Carvalho Chehab 2021-06-10 23:46 ` Bjorn Helgaas 2021-06-05 13:18 ` [PATCH 28/34] docs: process: submitting-patches.rst: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 29/34] docs: security: landlock.rst: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 30/34] docs: trace: coresight: coresight.rst: " Mauro Carvalho Chehab 2021-06-05 13:18 ` Mauro Carvalho Chehab 2021-06-08 15:23 ` Mathieu Poirier 2021-06-08 15:23 ` Mathieu Poirier 2021-06-05 13:18 ` [PATCH 31/34] docs: trace: ftrace.rst: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 32/34] docs: userspace-api: landlock.rst: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 33/34] docs: virt: kvm: s390-pv-boot.rst: " Mauro Carvalho Chehab 2021-06-05 13:18 ` [PATCH 34/34] docs: x86: " Mauro Carvalho Chehab 2021-06-07 15:21 ` Peter Zijlstra 2021-06-05 13:37 ` [PATCH 00/34] docs: avoid using ReST :doc:`foo` tag Mauro Carvalho Chehab 2021-06-05 13:37 ` Mauro Carvalho Chehab 2021-06-05 15:11 ` Nícolas F. R. A. Prado 2021-06-05 15:11 ` Nícolas F. R. A. Prado 2021-06-05 19:08 ` Mauro Carvalho Chehab 2021-06-05 19:08 ` Mauro Carvalho Chehab 2021-06-06 22:52 ` Nícolas F. R. A. Prado 2021-06-06 22:52 ` Nícolas F. R. A. Prado 2021-06-07 7:34 ` Mauro Carvalho Chehab 2021-06-07 7:34 ` Mauro Carvalho Chehab 2021-06-08 0:34 ` Nícolas F. R. A. Prado [this message] 2021-06-08 0:34 ` Nícolas F. R. A. Prado 2021-06-08 7:28 ` Mauro Carvalho Chehab 2021-06-08 7:28 ` Mauro Carvalho Chehab
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20210608003458.kwhbn6mraekcutlt@notapiano \ --to=n@nfraprado.net \ --cc=bpf@vger.kernel.org \ --cc=corbet@lwn.net \ --cc=coresight@lists.linaro.org \ --cc=devicetree@vger.kernel.org \ --cc=kunit-dev@googlegroups.com \ --cc=kvm@vger.kernel.org \ --cc=linux-acpi@vger.kernel.org \ --cc=linux-arm-kernel@lists.infradead.org \ --cc=linux-doc@vger.kernel.org \ --cc=linux-gpio@vger.kernel.org \ --cc=linux-hwmon@vger.kernel.org \ --cc=linux-i2c@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-kselftest@vger.kernel.org \ --cc=linux-media@vger.kernel.org \ --cc=linux-pci@vger.kernel.org \ --cc=linux-pm@vger.kernel.org \ --cc=linux-security-module@vger.kernel.org \ --cc=mchehab+huawei@kernel.org \ --cc=netdev@vger.kernel.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.