Em Wed, 7 Oct 2020 10:32:27 +0300
Ivan Zaentsev <ivan.zaent...@wirenboard.ru> escreveu:
> Tuesday, October 6, 2020, 4:19:15 PM, Mauro Carvalho Chehab wrote:
>
> >> diff --git a/Documentation/w1/slaves/w1_therm.rst
> >> b/Documentation/w1/slaves/w1_therm.rst
> >> index f1148181f53e..00376501a5ef 100644
> >> --- a/Documentation/w1/slaves/w1_therm.rst
> >> +++ b/Documentation/w1/slaves/w1_therm.rst
>
> >>
> >> @@ -130,4 +131,12 @@ conversion and temperature reads 85.00 (powerup
> >> value) or 127.94 (insufficient
> >> power), the driver returns a conversion error. Bit mask ``2`` enables
> >> poll for
> >> conversion completion (normal power only) by generating read cycles on
> >> the bus
> >> after conversion starts. In parasite power mode this feature is not
> >> available.
> >> -Feature bit masks may be combined (OR).
> >> +Feature bit masks may be combined (OR). See accompanying sysfs
> >> documentation:
> >> +:ref:`Documentation/w1/slaves/w1_therm.rst <w1_therm>`
> >> +
>
> > As warned by Sphinx, this cross-reference is broken:
>
> > .../Documentation/w1/slaves/w1_therm.rst:125: WARNING:
> > undefined label: w1_therm (if the link has no caption the label must
> > precede a section header)
>
> Would this be ok?
Yeah, sure!
>
> "More details in Documentation/ABI/testing/sysfs-driver-w1_therm"
>
> > Not sure what you wanted to point here.
>
> A link to a driver's sysfs interface, but sysfs docs are text
> files and seem to not be included in Sphynx Docs.
I sent upstream sometime ago a patch series adding ABI to Sphinx, but I
was not merged, not sure why:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v5.6
Yet, the approach such series took were not to convert ABI files
to ReST, but, instead, to use a script that would do that.
The rationale were to avoid needing to touch all ABI files at
the same time[1].
In any case, with such approach a cross-reference won't work.
So, I guess that the next best thing to do is to just mention
the file like what you suggested.
[1] It would be easy to run the script I wrote to convert the
files to ReST directly.
Thanks,
Mauro
