[PATCH 0/4] Documentation/ABI: platform/x86: Sphinx warning fixes

[PATCH 0/4] Documentation/ABI: platform/x86: Sphinx warning fixes

[Hans de Goede]

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(-)

-- 
2.35.1

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

[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).

Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
---
 .../ABI/testing/sysfs-driver-intel_sdsi        | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-driver-intel_sdsi b/Documentation/ABI/testing/sysfs-driver-intel_sdsi
index ab122125ff9a..96b92c105ec4 100644
--- a/Documentation/ABI/testing/sysfs-driver-intel_sdsi
+++ b/Documentation/ABI/testing/sysfs-driver-intel_sdsi
@@ -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
-- 
2.35.1

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

[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.

Signed-off-by: Hans de Goede <hdegoede@redhat.com>
---
 .../testing/sysfs-class-firmware-attributes   | 42 ++++++++++---------
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes
index 05820365f1ec..5356ff2ed6c8 100644
--- a/Documentation/ABI/testing/sysfs-class-firmware-attributes
+++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes
@@ -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
-- 
2.35.1

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

[Hans de Goede]

Cleanup / fix some minor issues.

Signed-off-by: Hans de Goede <hdegoede@redhat.com>
---
 Documentation/ABI/testing/sysfs-class-firmware-attributes | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes
index 5356ff2ed6c8..4cdba3477176 100644
--- a/Documentation/ABI/testing/sysfs-class-firmware-attributes
+++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes
@@ -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.
-- 
2.35.1

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

[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

Signed-off-by: Hans de Goede <hdegoede@redhat.com>
---
 Documentation/ABI/testing/sysfs-class-power | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
index fde21d900420..859501366777 100644
--- a/Documentation/ABI/testing/sysfs-class-power
+++ b/Documentation/ABI/testing/sysfs-class-power
@@ -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
-- 
2.35.1

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

[Mark Pearson]

Thanks Hans

On 3/24/22 12:47, Hans de Goede wrote:
> Fix the following warnings from "make htmldocs":
> 
> Documentation/ABI/testing/sysfs-class-firmware-attributes:130:
>   ERROR: Unexpected indentation.
>   ERROR: Unexpected indentation.
>   ERROR: Unexpected indentation.
> 
> Signed-off-by: Hans de Goede <hdegoede@redhat.com>
> ---
>  .../testing/sysfs-class-firmware-attributes   | 42 ++++++++++---------
>  1 file changed, 23 insertions(+), 19 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes
> index 05820365f1ec..5356ff2ed6c8 100644
> --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes
> +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes
> @@ -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

Looks good!
Mark

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

[Mark Pearson]

On 3/24/22 12:47, Hans de Goede wrote:
> Cleanup / fix some minor issues.
> 
> Signed-off-by: Hans de Goede <hdegoede@redhat.com>
> ---
>  Documentation/ABI/testing/sysfs-class-firmware-attributes | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-firmware-attributes b/Documentation/ABI/testing/sysfs-class-firmware-attributes
> index 5356ff2ed6c8..4cdba3477176 100644
> --- a/Documentation/ABI/testing/sysfs-class-firmware-attributes
> +++ b/Documentation/ABI/testing/sysfs-class-firmware-attributes
> @@ -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.
Looks good - thanks for taking care of this
Mark

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

[David E. Box]

On Thu, 2022-03-24 at 17:47 +0100, Hans de Goede wrote:
> 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

> 
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: Hans de Goede <hdegoede@redhat.com>
> ---
>  .../ABI/testing/sysfs-driver-intel_sdsi        | 18 ++++++++++--------
>  1 file changed, 10 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-driver-intel_sdsi
> b/Documentation/ABI/testing/sysfs-driver-intel_sdsi
> index ab122125ff9a..96b92c105ec4 100644
> --- a/Documentation/ABI/testing/sysfs-driver-intel_sdsi
> +++ b/Documentation/ABI/testing/sysfs-driver-intel_sdsi
> @@ -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

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

[Hans de Goede]

Hi,

On 3/24/22 17:47, Hans de Goede wrote:
> 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
> 
> Signed-off-by: Hans de Goede <hdegoede@redhat.com>
> ---
>  Documentation/ABI/testing/sysfs-class-power | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
> index fde21d900420..859501366777 100644
> --- a/Documentation/ABI/testing/sysfs-class-power
> +++ b/Documentation/ABI/testing/sysfs-class-power
> @@ -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