Skip to contentSkip to conversation

Documentation/ABI/testing: Sphinx warning fixes

PATCH In review Hans de Goede 2 participants 6 messages Mar 24, 2022 – Mar 25, 2022

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

cover Documentation/ABI/testing: Sphinx warning fixes

Hi All,

After Stephen reported some Sphinx warnings for the platform-drivers-x86, I had to first figure out how to reproduce these. It turns out that to regenerate the htmldocs for Documentation/ABI/testing one has to run:

touch Documentation/admin-guide/abi-testing.rst && make htmldocs

This turned up not only warnings from platform/x86 driver ABI but also for some others. While at it I've written fixes for those too.

I'm not sure how these should be merged, I guess that the relevant subsys maintainers will pick these up?

Regards,

Hans

Hans de Goede (3):
Documentation/ABI: sysfs-driver-aspeed-uart-routing: Fix sphinx
warning
Documentation/ABI: sysfs-class-thermal: Fix Sphinx warning Documentation/ABI: sysfs-fs-erofs: Fix Sphinx errors

 Documentation/ABI/testing/sysfs-class-thermal              | 2 +-
 Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing | 7 ++++---
 Documentation/ABI/testing/sysfs-fs-erofs                   | 5 +++--
 3 files changed, 8 insertions(+), 6 deletions(-)
Signature · 1 line
2.35.1
#1 lore raw

PATCH 1/3 Documentation/ABI: sysfs-driver-aspeed-uart-routing: Fix sphinx warning

Fix the following warning from "make htmldocs":

Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing:2:
WARNING: Inline emphasis start-string without end-string.

This is caused by the used of '*' in the example cat command, mark the command as code to fix this.

---
 Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing +4 -3
index b363827da437..1e25cd2cacc1 100644
@@ -8,9 +8,10 @@ Description:	Selects the RX source of the UARTx device.
 		selected option marked by brackets "[]". The list of available options
 		depends on the selected file.
 
-		e.g.
-		cat /sys/bus/platform/drivers/aspeed-uart-routing/*.uart_routing/uart1
-		[io1] io2 io3 io4 uart2 uart3 uart4 io6
+		e.g.::
+
+			# cat /sys/bus/platform/drivers/aspeed-uart-routing/*.uart_routing/uart1
+			[io1] io2 io3 io4 uart2 uart3 uart4 io6
 
 		In this case, UART1 gets its input from IO1 (physical serial port 1).
 
Signature · 1 line
2.35.1
#2 lore raw

Re: [PATCH 1/3] Documentation/ABI: sysfs-driver-aspeed-uart-routing: Fix sphinx warning

Hi,

Quoted 9 lines · Hans de Goede

Fix the following warning from "make htmldocs":

Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing:2:
WARNING: Inline emphasis start-string without end-string.

This is caused by the used of '*' in the example cat command, mark the command as code to fix this.

I see that this was already fixed by escaping the '*' with a '\', apologies.

So this patch can be ignored / dropped.

Regards,

Hans

Quoted 22 lines
---
 Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/ABI/testing/sysfs-driver-aspeed-uart-routing +4 -3
index b363827da437..1e25cd2cacc1 100644
@@ -8,9 +8,10 @@ Description:	Selects the RX source of the UARTx device.
 		selected option marked by brackets "[]". The list of available options
 		depends on the selected file.
 
-		e.g.
-		cat /sys/bus/platform/drivers/aspeed-uart-routing/*.uart_routing/uart1
-		[io1] io2 io3 io4 uart2 uart3 uart4 io6
+		e.g.::
+
+			# cat /sys/bus/platform/drivers/aspeed-uart-routing/*.uart_routing/uart1
+			[io1] io2 io3 io4 uart2 uart3 uart4 io6
 
 		In this case, UART1 gets its input from IO1 (physical serial port 1).
 
#3 lore raw

PATCH 2/3 Documentation/ABI: sysfs-class-thermal: Fix Sphinx warning

In reply to Hans de Goede

Fix the following warning from "make htmldocs":

Documentation/ABI/testing/sysfs-class-thermal:201:
WARNING: Bullet list ends without a blank line; unexpected unindent.

---
 Documentation/ABI/testing/sysfs-class-thermal | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/ABI/testing/sysfs-class-thermal +1 -1
index 2c52bb1f864c..8eee37982b2a 100644
@@ -203,7 +203,7 @@ Description:
 
 		- for generic ACPI: should be "Fan", "Processor" or "LCD"
 		- for memory controller device on intel_menlow platform:
-		should be "Memory controller".
+		  should be "Memory controller".
 
 		RO, Required
 
Signature · 1 line
2.35.1
#4 lore raw

PATCH 3/3 Documentation/ABI: sysfs-fs-erofs: Fix Sphinx errors

In reply to Hans de Goede

Fix the following warnings from "make htmldocs":

Documentation/ABI/testing/sysfs-fs-erofs:10:
ERROR: Unexpected indentation.
WARNING: Block quote ends without a blank line; unexpected unindent.

---
 Documentation/ABI/testing/sysfs-fs-erofs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/ABI/testing/sysfs-fs-erofs +3 -2
index 05482374a741..bb4681a01811 100644
@@ -9,8 +9,9 @@ Description:	Shows all enabled kernel features.
 What:		/sys/fs/erofs/<disk>/sync_decompress
 Date:		November 2021
 Contact:	"Huang Jianan" <[email protected]>
-Description:	Control strategy of sync decompression
+Description:	Control strategy of sync decompression:
+
 		- 0 (default, auto): enable for readpage, and enable for
-				     readahead on atomic contexts only,
+		  readahead on atomic contexts only.
 		- 1 (force on): enable for readpage and readahead.
 		- 2 (force off): disable for all situations.
Signature · 1 line
2.35.1
Acked-by on v1 3/3
#5 lore raw

Re: [PATCH 3/3] Documentation/ABI: sysfs-fs-erofs: Fix Sphinx errors

Quoted 7 lines · Hans de Goede

Fix the following warnings from "make htmldocs":

Documentation/ABI/testing/sysfs-fs-erofs:10:
ERROR: Unexpected indentation.
WARNING: Block quote ends without a blank line; unexpected unindent.

Thanks!

Thanks,
Gao Xiang

Quoted 22 lines
---
 Documentation/ABI/testing/sysfs-fs-erofs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/ABI/testing/sysfs-fs-erofs +3 -2
index 05482374a741..bb4681a01811 100644
@@ -9,8 +9,9 @@ Description:	Shows all enabled kernel features.
 What:		/sys/fs/erofs/<disk>/sync_decompress
 Date:		November 2021
 Contact:	"Huang Jianan" <[email protected]>
-Description:	Control strategy of sync decompression
+Description:	Control strategy of sync decompression:
+
 		- 0 (default, auto): enable for readpage, and enable for
-				     readahead on atomic contexts only,
+		  readahead on atomic contexts only.
 		- 1 (force on): enable for readpage and readahead.
 		- 2 (force off): disable for all situations.
Signature · 1 line
2.35.1