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
next prev parent reply other threads:[~2021-06-08 0:35 UTC|newest]
Thread overview: 63+ 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: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-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 15:11 ` Nícolas F. R. A. Prado
2021-06-05 19:08 ` Mauro Carvalho Chehab
2021-06-06 22:52 ` Nícolas F. R. A. Prado
2021-06-07 7:34 ` Mauro Carvalho Chehab
2021-06-08 0:34 ` Nícolas F. R. A. Prado [this message]
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: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).