Skip to contentSkip to conversation

Documentation/ABI: platform/x86: Sphinx warning fixes

PATCH In review Hans de Goede 3 participants 9 messages Mar 24, 2022 – Mar 25, 2022

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

cover Documentation/ABI: platform/x86: Sphinx warning fixes

Hi All,

After Stephen reported some Sphinx warnings for files under Documentation/ABI/testing, I had to first figure out how to reproduce these. It turns out that to regenerate the htmldocs for files under Documentation/ABI/testing once has to run:

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

This turned up warnings in multiple sysfs ABI files for platform/x86 drivers, as well as in some new functionality in sysfs-class-power, which was merged through the platform-drivers-x86 tree.

I plan to merge this series through the platform-drivers-x86 tree and send this out in a fixed pull-req to Linus once 5.18-rc1 is out.

Regards,

Hans

p.s.

platform-drivers-x86 authors, for future patch submissions touching files under Documentation/ABI/testing please run:

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

and make sure no warnings are introduced.

Hans de Goede (4):
Documentation/ABI: sysfs-driver-intel_sdsi: Fix sphinx warnings Documentation/ABI: sysfs-class-firmware-attributes: Fix Sphinx errors Documentation/ABI: sysfs-class-firmware-attributes: Misc. cleanups Documentation/ABI: sysfs-class-power: Fix Sphinx error

 .../testing/sysfs-class-firmware-attributes   | 48 ++++++++++---------
 Documentation/ABI/testing/sysfs-class-power   |  1 +
 .../ABI/testing/sysfs-driver-intel_sdsi       | 18 +++----
 3 files changed, 37 insertions(+), 30 deletions(-)
Signature · 1 line
2.35.1
#1 lore raw

PATCH 1/4 Documentation/ABI: sysfs-driver-intel_sdsi: Fix sphinx warnings

Fix the following warnings from "make htmldocs":

Documentation/ABI/testing/sysfs-driver-intel_sdsi:2:
WARNING: Unexpected indentation.
WARNING: Block quote ends without a blank line; unexpected unindent.
WARNING: Definition list ends without a blank line; unexpected unindent.

By turning the error-code table into a proper ReST table. While at it also fix the error-code table mixing tab and spaces for indentation (switch to all tabs).

---
 .../ABI/testing/sysfs-driver-intel_sdsi        | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)
Documentation/ABI/testing/sysfs-driver-intel_sdsi +10 -8
index ab122125ff9a..96b92c105ec4 100644
@@ -13,17 +13,19 @@ Description:
 		Should the operation fail, one of the following error codes
 		may be returned:
 
+		==========	=====
 		Error Code	Cause
-	        ----------	-----
-	        EIO		General mailbox failure. Log may indicate cause.
-	        EBUSY		Mailbox is owned by another agent.
-	        EPERM		SDSI capability is not enabled in hardware.
-	        EPROTO		Failure in mailbox protocol detected by driver.
+		==========	=====
+		EIO		General mailbox failure. Log may indicate cause.
+		EBUSY		Mailbox is owned by another agent.
+		EPERM		SDSI capability is not enabled in hardware.
+		EPROTO		Failure in mailbox protocol detected by driver.
 				See log for details.
-	        EOVERFLOW	For provision commands, the size of the data
+		EOVERFLOW	For provision commands, the size of the data
 				exceeds what may be written.
-	        ESPIPE		Seeking is not allowed.
-	        ETIMEDOUT	Failure to complete mailbox transaction in time.
+		ESPIPE		Seeking is not allowed.
+		ETIMEDOUT	Failure to complete mailbox transaction in time.
+		==========	=====
 
 What:		/sys/bus/auxiliary/devices/intel_vsec.sdsi.X/guid
 Date:		Feb 2022
Signature · 1 line
2.35.1
#2 lore raw

Re: [PATCH 1/4] Documentation/ABI: sysfs-driver-intel_sdsi: Fix sphinx warnings

Quoted 10 lines · Hans de Goede

Fix the following warnings from "make htmldocs":

Documentation/ABI/testing/sysfs-driver-intel_sdsi:2:
WARNING: Unexpected indentation.
WARNING: Block quote ends without a blank line; unexpected unindent.
WARNING: Definition list ends without a blank line; unexpected unindent.

By turning the error-code table into a proper ReST table. While at it also fix the error-code table mixing tab and spaces for indentation (switch to all tabs).

Thanks for the fix and for clarifying how to reproduce.

David

Quoted 44 lines
---
 .../ABI/testing/sysfs-driver-intel_sdsi        | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)
Documentation/ABI/testing/sysfs-driver-intel_sdsi +1 -2
index ab122125ff9a..96b92c105ec4 100644
@@ -13,17 +13,19 @@ Description:
 		Should the operation fail, one of the following error codes
 		may be returned:
 
+		==========	=====
 		Error Code	Cause
-	        ----------	-----
-	        EIO		General mailbox failure. Log may indicate

cause.

Documentation/ABI/testing/sysfs-driver-intel_sdsi +0 -3
-	        EBUSY		Mailbox is owned by another agent.
-	        EPERM		SDSI capability is not enabled in hardware.
-	        EPROTO		Failure in mailbox protocol detected by

driver.

Documentation/ABI/testing/sysfs-driver-intel_sdsi +2 -0
+		==========	=====
+		EIO		General mailbox failure. Log may indicate

cause.

Documentation/ABI/testing/sysfs-driver-intel_sdsi +3 -0
+		EBUSY		Mailbox is owned by another agent.
+		EPERM		SDSI capability is not enabled in hardware.
+		EPROTO		Failure in mailbox protocol detected by

driver.

Documentation/ABI/testing/sysfs-driver-intel_sdsi +4 -3
 				See log for details.
-	        EOVERFLOW	For provision commands, the size of the data
+		EOVERFLOW	For provision commands, the size of the data
 				exceeds what may be written.
-	        ESPIPE		Seeking is not allowed.
-	        ETIMEDOUT	Failure to complete mailbox transaction in time.
+		ESPIPE		Seeking is not allowed.
+		ETIMEDOUT	Failure to complete mailbox transaction in time.
+		==========	=====
 
 What:		/sys/bus/auxiliary/devices/intel_vsec.sdsi.X/guid
 Date:		Feb 2022
#3 lore raw

PATCH 2/4 Documentation/ABI: sysfs-class-firmware-attributes: Fix Sphinx errors

In reply to Hans de Goede

Fix the following warnings from "make htmldocs":

Documentation/ABI/testing/sysfs-class-firmware-attributes:130:
ERROR: Unexpected indentation.
ERROR: Unexpected indentation.
ERROR: Unexpected indentation.

---
 .../testing/sysfs-class-firmware-attributes   | 42 ++++++++++---------
 1 file changed, 23 insertions(+), 19 deletions(-)
Documentation/ABI/testing/sysfs-class-firmware-attributes +23 -19
index 05820365f1ec..5356ff2ed6c8 100644
@@ -246,9 +246,7 @@ Description:
 					that is being referenced (e.g hdd0, hdd1 etc)
 					This attribute defaults to device 0.
 
-		certificate:
-		signature:
-		save_signature:
+		certificate, signature, save_signature:
 					These attributes are used for certificate based authentication. This is
 					used in conjunction with a signing server as an alternative to password
 					based authentication.
@@ -257,22 +255,27 @@ Description:
 					The attributes can be displayed to check the stored value.
 
 					Some usage examples:
-					Installing a certificate to enable feature:
-						echo <supervisor password > authentication/Admin/current_password
-						echo <signed certificate> > authentication/Admin/certificate
 
-					Updating the installed certificate:
-						echo <signature> > authentication/Admin/signature
-						echo <signed certificate> > authentication/Admin/certificate
+						Installing a certificate to enable feature::
 
-					Removing the installed certificate:
-						echo <signature> > authentication/Admin/signature
-						echo '' > authentication/Admin/certificate
+							echo "supervisor password" > authentication/Admin/current_password
+							echo "signed certificate" > authentication/Admin/certificate
 
-					Changing a BIOS setting:
-						echo <signature> > authentication/Admin/signature
-						echo <save signature> > authentication/Admin/save_signature
-						echo Enable > attribute/PasswordBeep/current_value
+						Updating the installed certificate::
+
+							echo "signature" > authentication/Admin/signature
+							echo "signed certificate" > authentication/Admin/certificate
+
+						Removing the installed certificate::
+
+							echo "signature" > authentication/Admin/signature
+							echo "" > authentication/Admin/certificate
+
+						Changing a BIOS setting::
+
+							echo "signature" > authentication/Admin/signature
+							echo "save signature" > authentication/Admin/save_signature
+							echo Enable > attribute/PasswordBeep/current_value
 
 					You cannot enable certificate authentication if a supervisor password
 					has not been set.
@@ -288,9 +291,10 @@ Description:
 		certificate_to_password:
 					Write only attribute used to switch from certificate based authentication
 					back to password based.
-					Usage:
-						echo <signature> > authentication/Admin/signature
-						echo <password> > authentication/Admin/certificate_to_password
+					Usage::
+
+						echo "signature" > authentication/Admin/signature
+						echo "password" > authentication/Admin/certificate_to_password
 
 
 What:		/sys/class/firmware-attributes/*/attributes/pending_reboot
Signature · 1 line
2.35.1
#4 lore raw

Re: [External] [PATCH 2/4] Documentation/ABI: sysfs-class-firmware-attributes: Fix Sphinx errors

Thanks Hans

Quoted 72 lines · Hans de Goede

Fix the following warnings from "make htmldocs":

Documentation/ABI/testing/sysfs-class-firmware-attributes:130:
ERROR: Unexpected indentation.
ERROR: Unexpected indentation.
ERROR: Unexpected indentation.

---
 .../testing/sysfs-class-firmware-attributes   | 42 ++++++++++---------
 1 file changed, 23 insertions(+), 19 deletions(-)
Documentation/ABI/testing/sysfs-class-firmware-attributes +19 -16
index 05820365f1ec..5356ff2ed6c8 100644
@@ -246,9 +246,7 @@ Description:
 					that is being referenced (e.g hdd0, hdd1 etc)
 					This attribute defaults to device 0.
 
-		certificate:
-		signature:
-		save_signature:
+		certificate, signature, save_signature:
 					These attributes are used for certificate based authentication. This is
 					used in conjunction with a signing server as an alternative to password
 					based authentication.
@@ -257,22 +255,27 @@ Description:
 					The attributes can be displayed to check the stored value.
 
 					Some usage examples:
-					Installing a certificate to enable feature:
-						echo <supervisor password > authentication/Admin/current_password
-						echo <signed certificate> > authentication/Admin/certificate
 
-					Updating the installed certificate:
-						echo <signature> > authentication/Admin/signature
-						echo <signed certificate> > authentication/Admin/certificate
+						Installing a certificate to enable feature::
 
-					Removing the installed certificate:
-						echo <signature> > authentication/Admin/signature
-						echo '' > authentication/Admin/certificate
+							echo "supervisor password" > authentication/Admin/current_password
+							echo "signed certificate" > authentication/Admin/certificate
 
-					Changing a BIOS setting:
-						echo <signature> > authentication/Admin/signature
-						echo <save signature> > authentication/Admin/save_signature
-						echo Enable > attribute/PasswordBeep/current_value
+						Updating the installed certificate::
+
+							echo "signature" > authentication/Admin/signature
+							echo "signed certificate" > authentication/Admin/certificate
+
+						Removing the installed certificate::
+
+							echo "signature" > authentication/Admin/signature
+							echo "" > authentication/Admin/certificate
+
+						Changing a BIOS setting::
+
+							echo "signature" > authentication/Admin/signature
+							echo "save signature" > authentication/Admin/save_signature
+							echo Enable > attribute/PasswordBeep/current_value
 
 					You cannot enable certificate authentication if a supervisor password
 					has not been set.
@@ -288,9 +291,10 @@ Description:
 		certificate_to_password:
 					Write only attribute used to switch from certificate based authentication
 					back to password based.

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 300

Quoted 10 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +4 -3
-					Usage:
-						echo <signature> > authentication/Admin/signature
-						echo <password> > authentication/Admin/certificate_to_password
+					Usage::
+
+						echo "signature" > authentication/Admin/signature
+						echo "password" > authentication/Admin/certificate_to_password
 
 
 What:		/sys/class/firmware-attributes/*/attributes/pending_reboot

Looks good!
Mark

#5 lore raw

PATCH 3/4 Documentation/ABI: sysfs-class-firmware-attributes: Misc. cleanups

In reply to Hans de Goede

Cleanup / fix some minor issues.

---
 Documentation/ABI/testing/sysfs-class-firmware-attributes | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/ABI/testing/sysfs-class-firmware-attributes +3 -3
index 5356ff2ed6c8..4cdba3477176 100644
@@ -116,7 +116,7 @@ Description:
 					    <value>[ForceIf:<attribute>=<value>]
 					    <value>[ForceIfNot:<attribute>=<value>]
 
-					For example:
+					For example::
 
 					    LegacyOrom/dell_value_modifier has value:
 						    Disabled[ForceIf:SecureBoot=Enabled]
@@ -212,7 +212,7 @@ Description:
 		the next boot.
 
 		Lenovo specific class extensions
-		------------------------------
+		--------------------------------
 
 		On Lenovo systems the following additional settings are available:
 
@@ -349,7 +349,7 @@ Description:
 
 		    # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
 		    # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
-		    # builtinsafe lastknowngood [factory] custom
+		    builtinsafe lastknowngood [factory] custom
 
 		Note that any changes to this attribute requires a reboot
 		for changes to take effect.
Signature · 1 line
2.35.1
#6 lore raw

Re: [External] [PATCH 3/4] Documentation/ABI: sysfs-class-firmware-attributes: Misc. cleanups

Quoted 30 lines · Hans de Goede

Cleanup / fix some minor issues.

---
 Documentation/ABI/testing/sysfs-class-firmware-attributes | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/ABI/testing/sysfs-class-firmware-attributes +2 -2
index 5356ff2ed6c8..4cdba3477176 100644
@@ -116,7 +116,7 @@ Description:
 					    <value>[ForceIf:<attribute>=<value>]
 					    <value>[ForceIfNot:<attribute>=<value>]
 
-					For example:
+					For example::
 
 					    LegacyOrom/dell_value_modifier has value:
 						    Disabled[ForceIf:SecureBoot=Enabled]
@@ -212,7 +212,7 @@ Description:
 		the next boot.
 
 		Lenovo specific class extensions
-		------------------------------
+		--------------------------------
 
 		On Lenovo systems the following additional settings are available:
 

Documentation/ABI/testing/sysfs-class-firmware-attributes Description: · line 355

Quoted 8 lines
Documentation/ABI/testing/sysfs-class-firmware-attributes +1 -1
@@ -349,7 +349,7 @@ Description:
 
 		    # echo "factory" > /sys/class/firmware-attributes/*/device/attributes/reset_bios
 		    # cat /sys/class/firmware-attributes/*/device/attributes/reset_bios
-		    # builtinsafe lastknowngood [factory] custom
+		    builtinsafe lastknowngood [factory] custom
 
 		Note that any changes to this attribute requires a reboot
 		for changes to take effect.

Looks good - thanks for taking care of this
Mark

#7 lore raw

PATCH 4/4 Documentation/ABI: sysfs-class-power: Fix Sphinx error

In reply to Hans de Goede

Fix the following error from "make htmldocs":

Documentation/ABI/testing/sysfs-class-power:459: ERROR:
No bottom table border found.

================ ====================================

auto:            Charge normally, respect thresholds
inhibit-charge:  Do not charge while AC is attached
force-discharge: Force discharge while AC is attached
---
 Documentation/ABI/testing/sysfs-class-power | 1 +
 1 file changed, 1 insertion(+)
Documentation/ABI/testing/sysfs-class-power +1 -0
index fde21d900420..859501366777 100644
@@ -468,6 +468,7 @@ Description:
 			auto:            Charge normally, respect thresholds
 			inhibit-charge:  Do not charge while AC is attached
 			force-discharge: Force discharge while AC is attached
+			================ ====================================
 
 What:		/sys/class/power_supply/<supply_name>/technology
 Date:		May 2007
Signature · 1 line
2.35.1
#8 lore raw

Re: [PATCH 4/4] Documentation/ABI: sysfs-class-power: Fix Sphinx error

Hi,

Quoted 20 lines · Hans de Goede

Fix the following error from "make htmldocs":

Documentation/ABI/testing/sysfs-class-power:459: ERROR:
No bottom table border found.

================ ====================================

auto:            Charge normally, respect thresholds
inhibit-charge:  Do not charge while AC is attached
force-discharge: Force discharge while AC is attached
---
 Documentation/ABI/testing/sysfs-class-power | 1 +
 1 file changed, 1 insertion(+)
Documentation/ABI/testing/sysfs-class-power +0 -0
index fde21d900420..859501366777 100644

Documentation/ABI/testing/sysfs-class-power Description: · line 474

Quoted 7 lines
Documentation/ABI/testing/sysfs-class-power +1 -0
@@ -468,6 +468,7 @@ Description:
 			auto:            Charge normally, respect thresholds
 			inhibit-charge:  Do not charge while AC is attached
 			force-discharge: Force discharge while AC is attached
+			================ ====================================
 
 What:		/sys/class/power_supply/<supply_name>/technology
 Date:		May 2007

I see a similar change has already landed in linux-power-supply/for-next, so I'll drop this patch from the set.

Regards,

Hans