Re: [linux-next:master 3622/16987] htmldocs: Documentation/ABI/testing/sysfs-class-power-rt9467:1: WARNING: Inline emphasis start-string without end-string. [docutils]

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

On Mon, 19 Oct 2026 17:15:02 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:

> [for kernel-doc people]
> 
> On 10/15/26 1:11 AM, kernel test robot wrote:
> > Hi Waqar,
> > 
> > FYI, the error/warning still remains.
> > 
> > tree:   https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git master
> > head:   d419d682257d813f6cb7a28e42b35d0edf4ad038
> > commit: 3f21de6784a654503cc148169d1f59d89971da13 [3622/16987] power: supply: rt9467: Use POWER_SUPPLY_PROP_LOAD_SWITCH
> > compiler: clang version 22.1.8 (https://github.com/llvm/llvm-project ca7933e47d3a3451d81e72ac174dcb5aa28b59d1)
> > docutils: docutils (Docutils 0.21.2, Python 3.13.5, on linux)  
> 
> I am using:
> $ docutils --version
> docutils-3.13 (Docutils 0.23, Python 3.13.16, on linux)
> $ python3 --version
> Python 3.13.16
> 
> 
> > reproduce: (https://download.01.org/0day-ci/archive/20261015/202610151025.1g5IgCv2-lkp@intel.com/reproduce)
> > 
> > If you fix the issue in a separate patch/commit (i.e. not just a new version of
> > the same patch/commit), kindly add following tags
> > | Reported-by: kernel test robot <lkp@intel.com>
> > | Closes: https://lore.kernel.org/oe-kbuild-all/202610151025.1g5IgCv2-lkp@intel.com/
> > 
> > All warnings (new ones prefixed by >>):
> > 
> >    Using alabaster theme  
> 
> 
> >>> Documentation/ABI/testing/sysfs-class-power-rt9467:1: WARNING: Inline emphasis start-string without end-string. [docutils]  
> >    Documentation/ABI/testing/sysfs-class-power-rt9471:1: WARNING: Inline emphasis start-string without end-string. [docutils]  
> 
> and I only see one of these warnings (rt9467), although the sources
> for them are VERY similar.Why would that happen?
> Do we need to fix anything?
> 
> > vim +1 Documentation/ABI/testing/sysfs-class-power-rt9467
> > 
> > eedb923279b78cb ChiaEn Wu 2023-01-03 @1  What:		/sys/class/power_supply/rt9467-*/sysoff_enable

Getting just line 1 is wrong. See:

	$ ./tools/docs/get_abi.py -D Documentation/ABI/testing/ rest --enable-lineno|grep -A20 rt9467


	.. LINENO Documentation/ABI/testing/sysfs-class-power-rt9467#1


	.. _abi_sys_class_power_supply_rt9467_sysoff_enable:

	+-----------------------------------------------------------+
	| **\/sys\/class\/power_supply\/rt9467\-\*\/sysoff_enable** |
	+-----------------------------------------------------------+

	Defined on file :ref:`sysfs-class-power-rt9467 <abi_file_testing_sysfs_class_power_rt9467>`

	This entry allows enabling the sysoff mode of rt9467 charger
	devices.
	If enabled and the input is removed, the internal battery FET
	is turned off to reduce the leakage from the BAT pin. See
	device datasheet for details. It's commonly used when the
	product enter shipping stage. After entering shipping mode,
	only 'VBUS' or 'Power key" pressed can make it leave this mode.
	'Disable' also can help to leave it, but it's more like to
	abort the action before the device really enter shipping mode.

	Access: Read, Write
	Valid values:
	- 1: enabled
	- 0: disabled


	.. LINENO Documentation/ABI/testing/sysfs-class-power-rt9471#19

Just like kernel-doc, lines are incremented per symbol.

Line 1 means the sysfs data that starts on line 1. In this specific case,
I'm seeing two issues there:

- 'Power key" - I guess it won't generate a warning, but the quote
  types don't match.

- Here, blank lines are missing:

	Access: Read, Write
	Valid values:
	- 1: enabled
	- 0: disabled

  Causing this output:

	Access: Read, Write Valid values: - 1: enabled - 0: disabled

  The right way to format it would be:

	Access: Read, Write

	Valid values:

	- 1: enabled
	- 0: disabled

  As RST format considers a single "\n" as if the next line to be
  part of the same paragraph. So, to split paragraphs, a blank
  line is needed.


If you want to test it, I suggest placing the rst content on a file
and ask Sphinx to build it. What I usually do to test stuff created
via kernel-doc/get_abi/... is to create a:

	Documentation/<temp_dir>

adding there just an index file and the output I want to test.
Then, I use make with SPHINXDIRS=<temp_dir>, as this is a lot
faster than building the entire Kernel.

	$ mkdir Documentation/get_abi_tmp_dir
	$ ./tools/docs/get_abi.py -D Documentation/ABI/testing/ rest > Documentation/get_abi_tmp_dir/testing_abi.rst
	[WARNING] /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/os_mode is defined 2 times: Documentation/ABI/testing/sysfs-driver-hid-lenovo-go:364; Documentation/ABI/testing/sysfs-driver-hid-lenovo-go-s:234
	[WARNING] /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/os_mode_index is defined 2 times: Documentation/ABI/testing/sysfs-driver-hid-lenovo-go:373; Documentation/ABI/testing/sysfs-driver-hid-lenovo-go-s:243
	[WARNING] /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/touchpad/enabled is defined 2 times: Documentation/ABI/testing/sysfs-driver-hid-lenovo-go:636; Documentation/ABI/testing/sysfs-driver-hid-lenovo-go-s:252
	[WARNING] /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/touchpad/enabled_index is defined 2 times: Documentation/ABI/testing/sysfs-driver-hid-lenovo-go:645; Documentation/ABI/testing/sysfs-driver-hid-lenovo-go-s:261
	[INFO] Didn't find ABI reference for 'Documentation/ABI/stable/sysfs-devices-node'
	[INFO] Didn't find ABI reference for 'Documentation/ABI/stable/sysfs-devices-node'

	$ cat <<EOF > get_abi_tmp_dir/index.rst
	Test
	====

	.. toctree::
	   :maxdepth: 1

	   testing_abi
	EOF

	$ make SPHINXDIRS=get_abi_tmp_dir htmldocs

here, I'm placing the entire content of the abi testing, but you
could alternatively create a dir with a subset of files under ABI
and test only the ones that hits errors. Once fixed, you can copy
them back to the ABI directory.

Btw, at least here (docs/docs-mw branch), I can´t see any such
errors.
	
> > 
> > :::::: The code at line 1 was first introduced by commit
> > :::::: eedb923279b78cbfe16dd54dade0d73e9977f118 Documentation: power: rt9467: Document exported sysfs entries
> > 
> > :::::: TO: ChiaEn Wu <chiaen_wu@richtek.com>
> > :::::: CC: Sebastian Reichel <sre@kernel.org>  
> 



Thanks,
Mauro