Skip to contentSkip to conversation

docs: Fix warning:Error in "code-block" directive

PATCH In review Madhumitha Prabakaran 4 participants 5 messages Jun 2, 2023 – Jun 3, 2023 1 message not in the archive

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

PATCH 1/1 docs: Fix warning:Error in "code-block" directive

Fix the error in "code-block" directive by providing the argument as "text".

---
 .../firmware-guide/acpi/chromeos-acpi-device.rst          | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/firmware-guide/acpi/chromeos-acpi-device.rst +4 -4
index f37fc90ce340..27292299ad17 100644
@@ -131,7 +131,7 @@ None
 Result code:
 ------------
 
-.. code-block::
+.. code-block:: text
 
    Package {
            Reserved1
@@ -192,7 +192,7 @@ None
 
 Result code:
 ------------
-.. code-block::
+.. code-block:: text
 
         Package {
                 Package {
@@ -265,7 +265,7 @@ None
 
 Result code:
 ------------
-.. code-block::
+.. code-block:: text
 
         Package {
                 NV Storage Block Offset  //DWORD
@@ -347,7 +347,7 @@ A package containing a list of null-terminated ASCII strings, one for each contr
 supported by the Chrome OS hardware device, not including the MLST method itself.
 For this version of the specification, the result is:
 
-.. code-block::
+.. code-block:: text
 
         Package {
                 "CHSW",
Signature · 1 line
2.25.1
#1 lore raw
Quoted 9 lines · Madhumitha Prabakaran

Fix the error in "code-block" directive by providing the argument as "text".

<snipped> ...
Result code:
------------

-.. code-block::
+.. code-block:: text

Nope.

I don't see error you mention in this patch when making htmldocs on my computer (my setup is pretty standard: see Documentation/doc-guide/sphinx.rst). This patch is unneccessary, though, unless you have code snippets in some language (e.g. C, where passing language name to code-block:: syntax-highlight it). Result code outputs, on the other hand, are generic text with no definitive syntax, hence you can omit language name.

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
reviewer
#2 lore raw
Quoted 21 lines · Bagas Sanjaya
Quoted 9 lines · Madhumitha Prabakaran

Fix the error in "code-block" directive by providing the argument as "text".

<snipped> ...
Result code:
------------

-.. code-block::
+.. code-block:: text

Nope.

I don't see error you mention in this patch when making htmldocs on my computer (my setup is pretty standard: see Documentation/doc-guide/sphinx.rst). This patch is unneccessary, though, unless you have code snippets in some language (e.g. C, where passing language name to code-block:: syntax-highlight it). Result code outputs, on the other hand, are generic text with no definitive syntax, hence you can omit language name.

Quoted 1 line

Thanks.

I also don't see any such warnings so I don't see a need for this patch. My wild guess is that some older version of Sphinx was being used.

Signature · 1 line
~Randy
#3 lore raw
Quoted 22 lines · Randy Dunlap
Quoted 21 lines · Bagas Sanjaya
Quoted 9 lines · Madhumitha Prabakaran

Fix the error in "code-block" directive by providing the argument as "text".

<snipped> ...
Result code:
------------

-.. code-block::
+.. code-block:: text

Nope.

I don't see error you mention in this patch when making htmldocs on my computer (my setup is pretty standard: see Documentation/doc-guide/sphinx.rst). This patch is unneccessary, though, unless you have code snippets in some language (e.g. C, where passing language name to code-block:: syntax-highlight it). Result code outputs, on the other hand, are generic text with no definitive syntax, hence you can omit language name.

Quoted 5 lines
Quoted 1 line

Thanks.

I also don't see any such warnings so I don't see a need for this patch. My wild guess is that some older version of Sphinx was being used.

Right.

In Sphinx changelog, "Features added" for 2.0.0b1 [1] lists this:

#1851: Allow to omit an argument for code-block directive. If omitted, it follows highlight or highlight_language

[1]: https://www.sphinx-doc.org/en/master/changes.html#id1306

Pre-2.0 Sphinx is now deprecated.
See commit 31abfdda6527 ("docs: Deprecate use of Sphinx < 2.4.x").

Thanks, Akira

Quoted 3 lines
Signature · 2 lines
-- 
~Randy

A message that is not in the archive (sent off-list or not yet received): CAPNSgDiZiv6VJcX66DaQjHkLjd3ZxhkBcXzo7UU5LUD2hCx9Sw@mail.gmail.com

#5 lore raw
Quoted 16 lines · Madhumitha Prabakaran

Date: Sat, 3 Jun 2023 13:52:46 -0500
From: Madhumitha Prabakaran <[email protected]>
To: Madhumitha Prabakaran <[email protected]>
Subject: Fwd: [PATCH] docs: Fix warning:Error in "code-block" directive

---------- Forwarded message ---------
From: Akira Yokosawa <[email protected]>
Date: Fri, 2 Jun 2023 at 23:04
Subject: Re: [PATCH] docs: Fix warning:Error in "code-block" directive
To: <[email protected]>
Cc: <[email protected]>, <[email protected]>, <[email protected]>, < [email protected]>, <[email protected]>, < [email protected]>, <[email protected]>, <[email protected]>, <[email protected]>, Akira Yokosawa <[email protected]>

Quoted 18 lines
Quoted 17 lines · Randy Dunlap
Quoted 16 lines · Bagas Sanjaya
Quoted 9 lines · Madhumitha Prabakaran

Fix the error in "code-block" directive by providing the argument as "text".

<snipped> ...
Result code:
------------

-.. code-block::
+.. code-block:: text

Nope.

I don't see error you mention in this patch when making htmldocs on my computer (my setup is pretty standard: see Documentation/doc-guide/sphinx.rst). This patch is unneccessary, though,

I did executed "make htmldocs" on sphinx-build 1.8.5 and sphinx_2.4.4, which throws the warning but on executing the same on sphinx_7.1.0 - one can't see the warning

I skip the patch.

Thanks

Quoted 11 lines
Quoted 10 lines
Quoted 6 lines

unless you have code snippets in some language (e.g. C, where passing language name to code-block:: syntax-highlight it). Result code outputs, on the other hand, are generic text with no definitive syntax, hence you can omit language name.

Thanks.

I also don't see any such warnings so I don't see a need for this patch. My wild guess is that some older version of Sphinx was being used.

Yeah, your are right.
On executing the make htmldocs, it clearly throws the warning "WARNING: support for Sphinx < 2.4 will be removed soon"

My ignorance.

Thanks for pointing it.

Quoted 9 lines

Right.

In Sphinx changelog, "Features added" for 2.0.0b1 [1] lists this:

#1851: Allow to omit an argument for code-block directive. If omitted, it follows highlight or highlight_language

[1]: https://www.sphinx-doc.org/en/master/changes.html#id1306

Thanks for the changelog reference and reasoning.

Madhumitha

Quoted 8 lines

Pre-2.0 Sphinx is now deprecated.
See commit 31abfdda6527 ("docs: Deprecate use of Sphinx < 2.4.x").

Thanks, Akira

Quoted 3 lines

--
~Randy