Skip to contentSkip to conversation

doc: sphinx: Add sphinx-prompt

RFC PATCH In review Nishanth Menon 3 participants 12 messages Aug 24, 2023 – Aug 28, 2023

lore
Share & tools
lore
#0 lore raw

cover doc: sphinx: Add sphinx-prompt

Add Sphinx-prompt for more readable documentation and yet is userfriendly for people to copy paste.

See https://lore.kernel.org/all/[email protected]/

If this approach looks correct, please ack and I can convert the doc/board/ti/*.rst segments off to prompt instead of code-block where applicable.

Quick video to show the difference in experience: https://youtu.be/ylDrHXWGVgo

Nishanth Menon (2):
doc: sphinx: Add sphinx-prompt
doc: board: ti: k3: Convert to sphinx-prompt

 doc/board/ti/k3.rst         | 112 ++++++++++++++++++------------------
 doc/conf.py                 |   2 +-
 doc/sphinx/requirements.txt |   1 +
 3 files changed, 59 insertions(+), 56 deletions(-)
Signature · 1 line
2.40.0
#1 lore raw

RFC PATCH 1/2 doc: sphinx: Add sphinx-prompt

Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.

[1] https://lore.kernel.org/all/[email protected]/

---
Version picked is the best that works with Sphinx 3.4.3

 doc/conf.py                 | 2 +-
 doc/sphinx/requirements.txt | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)
doc/conf.py +1 -1
index 00f241366477..5e2ff1c8f5e2 100644
@@ -39,7 +39,7 @@ needs_sphinx = '2.4.4'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat', 'sphinx-prompt']
 
 #
 # cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
doc/sphinx/requirements.txt +1 -0
index 4f411f78d030..6ccbe527ee79 100644
@@ -15,6 +15,7 @@ requests==2.31.0
 six==1.16.0
 snowballstemmer==2.2.0
 Sphinx==3.4.3
+sphinx-prompt==1.5.0
 sphinx-rtd-theme==1.0.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
Signature · 1 line
2.40.0
#2 lore raw
Quoted 7 lines · Nishanth Menon

Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.

[1] https://lore.kernel.org/all/[email protected]/

Looks good to me.

Quoted 12 lines

---
Version picked is the best that works with Sphinx 3.4.3

  doc/conf.py                 | 2 +-
  doc/sphinx/requirements.txt | 1 +
  2 files changed, 2 insertions(+), 1 deletion(-)
doc/conf.py +0 -0
index 00f241366477..5e2ff1c8f5e2 100644

doc/conf.py needs_sphinx = '2.4.4' · line 42

Quoted 5 lines
doc/conf.py +1 -1
@@ -39,7 +39,7 @@ needs_sphinx = '2.4.4'
  extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
                'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
                'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat', 'sphinx-prompt']

We copied our conf.py from kernel.org. Please, check if it can be added upstream.

/linux$ scripts/get_maintainer.pl Documentation/conf.py Jonathan Corbet <[email protected]> (maintainer:DOCUMENTATION) [email protected] (open list:DOCUMENTATION) [email protected] (open list) [email protected] (open list:BPF [MISC])

Does the extension exist on their minimum Sphinx version (1.7) or at least on the 2.24 in Documentation/requirements.txt?

Best regards

Heinrich

Quoted 15 lines
doc/conf.py +0 -0
  #
  # cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
doc/sphinx/requirements.txt +1 -0
index 4f411f78d030..6ccbe527ee79 100644
@@ -15,6 +15,7 @@ requests==2.31.0
  six==1.16.0
  snowballstemmer==2.2.0
  Sphinx==3.4.3
+sphinx-prompt==1.5.0
  sphinx-rtd-theme==1.0.0
  sphinxcontrib-applehelp==1.0.2
  sphinxcontrib-devhelp==1.0.2
#3 lore raw
Quoted 18 lines · Heinrich Schuchardt
Quoted 7 lines · Nishanth Menon

Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.

[1] https://lore.kernel.org/all/[email protected]/

Looks good to me.

Quoted 7 lines

---
Version picked is the best that works with Sphinx 3.4.3

  doc/conf.py                 | 2 +-
  doc/sphinx/requirements.txt | 1 +
  2 files changed, 2 insertions(+), 1 deletion(-)
Quoted 13 lines

doc/conf.py needs_sphinx = '2.4.4' · line 42

Quoted 10 lines
doc/conf.py +1 -1
index 00f241366477..5e2ff1c8f5e2 100644
@@ -39,7 +39,7 @@ needs_sphinx = '2.4.4'
  extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
                'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
                'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat', 'sphinx-prompt']

We copied our conf.py from kernel.org. Please, check if it can be added upstream.

https://git.kernel.org/pub/scm/linux/kernel/git/ti/linux.git/tree/Documentation/sphinx/requirements.txt

Looks pretty different though :(

Quoted 9 lines

/linux$ scripts/get_maintainer.pl Documentation/conf.py Jonathan Corbet <[email protected]> (maintainer:DOCUMENTATION) [email protected] (open list:DOCUMENTATION) [email protected] (open list) [email protected] (open list:BPF [MISC])

Does the extension exist on their minimum Sphinx version (1.7) or at least on the 2.24 in Documentation/requirements.txt?

Trying things out, looks like sphinx-prompt 1.5.0 will work with 2.4.4 as well.

I am just a sphinx newbie.. I can propose, but taking the job up of a massive Documentation cleanup across kernel documentation is a bit beyond my availability.

If you think this is the way forward, then I can propose to the kernel list.

Quoted 20 lines

Best regards

Heinrich

Quoted 14 lines
doc/conf.py +0 -0
  #
  # cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
doc/sphinx/requirements.txt +1 -0
index 4f411f78d030..6ccbe527ee79 100644
@@ -15,6 +15,7 @@ requests==2.31.0
  six==1.16.0
  snowballstemmer==2.2.0
  Sphinx==3.4.3
+sphinx-prompt==1.5.0
  sphinx-rtd-theme==1.0.0
  sphinxcontrib-applehelp==1.0.2
  sphinxcontrib-devhelp==1.0.2
Signature · 3 lines
Regards,
Nishanth Menon
Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3  1A34 DDB5 849D 1736 249D
Reviewed-by on v1 1/2
#4 lore raw
In reply to Nishanth Menon
Quoted 7 lines · Nishanth Menon

Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.

[1] https://lore.kernel.org/all/[email protected]/

Reviewed-by on v1 1/2
#5 lore raw
In reply to Nishanth Menon
Quoted 7 lines · Nishanth Menon

Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a better rendered documentation, yet be able to copy paste without picking up the prompt from rendered documentation.

[1] https://lore.kernel.org/all/[email protected]/

Quoted 34 lines

---
Version picked is the best that works with Sphinx 3.4.3

 doc/conf.py                 | 2 +-
 doc/sphinx/requirements.txt | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)
doc/conf.py +1 -1
index 00f241366477..5e2ff1c8f5e2 100644
@@ -39,7 +39,7 @@ needs_sphinx = '2.4.4'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi', 'kernel_feat']
+              'kernel_abi', 'kernel_feat', 'sphinx-prompt']
 
 #
 # cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
doc/sphinx/requirements.txt +1 -0
index 4f411f78d030..6ccbe527ee79 100644
@@ -15,6 +15,7 @@ requests==2.31.0
 six==1.16.0
 snowballstemmer==2.2.0
 Sphinx==3.4.3
+sphinx-prompt==1.5.0
 sphinx-rtd-theme==1.0.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
Signature · 1 line
2.40.0
#6 lore raw

RFC PATCH 2/2 doc: board: ti: k3: Convert to sphinx-prompt

In reply to Nishanth Menon

Sphinx-prompt provides a handy scheme to provide documentation that renders nicely and yet provides a scheme to copy paste for users without having to hand-edit the copied text as is the result of code-block

[1] https://lore.kernel.org/all/[email protected]/

---
 doc/board/ti/k3.rst | 112 ++++++++++++++++++++++----------------------
 1 file changed, 57 insertions(+), 55 deletions(-)
doc/board/ti/k3.rst +57 -55
index 1175b776ad48..ec447358ac39 100644
@@ -194,13 +194,13 @@ All of that to say you will need both a 32bit and 64bit cross compiler
 .. k3_rst_include_end_common_env_vars_desc
 
 .. k3_rst_include_start_common_env_vars_defn
-.. code-block:: bash
+.. prompt:: bash
 
- $ export CC32=arm-linux-gnueabihf-
- $ export CC64=aarch64-linux-gnu-
- $ export LNX_FW_PATH=path/to/ti-linux-firmware
- $ export TFA_PATH=path/to/trusted-firmware-a
- $ export OPTEE_PATH=path/to/optee_os
+ export CC32=arm-linux-gnueabihf-
+ export CC64=aarch64-linux-gnu-
+ export LNX_FW_PATH=path/to/ti-linux-firmware
+ export TFA_PATH=path/to/trusted-firmware-a
+ export OPTEE_PATH=path/to/optee_os
 .. k3_rst_include_end_common_env_vars_defn
 
 We will also need some common environment variables set up for the various
@@ -244,11 +244,11 @@ Building tiboot3.bin
    uses the split binary flow)
 
 .. k3_rst_include_start_build_steps_spl_r5
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXR
- $ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
+ # inside u-boot source
+ make $UBOOT_CFG_CORTEXR
+ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
 .. k3_rst_include_end_build_steps_spl_r5
 
 At this point you should have all the needed binaries to boot the wakeup
@@ -280,11 +280,11 @@ firmware if your device using a split firmware.
    application cores on the main domain.
 
 .. k3_rst_include_start_build_steps_tfa
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside trusted-firmware-a source
- $ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
-        TARGET_BOARD=$TFA_BOARD
+ # inside trusted-firmware-a source
+ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
+      TARGET_BOARD=$TFA_BOARD
 .. k3_rst_include_end_build_steps_tfa
 
 Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD
@@ -296,11 +296,11 @@ use the `lite` option.
    using the TrustZone technology built into the core.
 
 .. k3_rst_include_start_build_steps_optee
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside optee_os source
- $ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
-         PLATFORM=$OPTEE_PLATFORM
+ # inside optee_os source
+ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
+       PLATFORM=$OPTEE_PLATFORM
 .. k3_rst_include_end_build_steps_optee
 
 4. Finally, after TF-A has initialized the main domain and OP-TEE has
@@ -308,11 +308,11 @@ use the `lite` option.
    64bit core in the main domain.
 
 .. k3_rst_include_start_build_steps_uboot
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXA
- $ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
+ # inside u-boot source
+ make $UBOOT_CFG_CORTEXA
+ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
         BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \
         TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin
 .. k3_rst_include_end_build_steps_uboot
@@ -407,14 +407,14 @@ and the same can be extended to other platforms
   be passing to mkimage for signing the fitImage and embedding the key in
   the u-boot dtb.
 
-  .. code-block:: bash
+  .. prompt:: bash
 
     mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
     $UBOOT_PATH/build/a72/dts/dt.dtb
 
   For signing a secondary platform, pass the -K parameter to that DTB
 
-  .. code-block:: bash
+  .. prompt:: bash
 
     mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
     $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb
@@ -473,10 +473,11 @@ then the saveenv command and can be used across various bootmodes too.
 
 **Writing to MMC/EMMC**
 
-.. code-block::
+.. prompt:: bash
+  :prompts: =>
 
-  => env export -t $loadaddr <list of variables>
-  => fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
+  env export -t $loadaddr <list of variables>
+  fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
 
 **Reading from MMC/EMMC**
 
@@ -486,10 +487,11 @@ mmcdev) and set the environments.
 If manually needs to be done then the environment can be read from the
 filesystem and then imported
 
-.. code-block::
+.. prompt:: bash
+  :prompts: =>
 
-  => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
-  => env import -t ${loadaddr} ${filesize}
+  fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
+  env import -t ${loadaddr} ${filesize}
 
 .. _k3_rst_refer_openocd:
 
@@ -546,7 +548,7 @@ Refer to the release notes corresponding to the `OpenOCD version
   box support by OpenOCD. The board-specific documentation will
   cover the details and any adapter/dongle recommendations.
 
-.. code-block:: bash
+.. prompt:: bash
 
  openocd -v
 
@@ -564,21 +566,21 @@ systems, but equivalent instructions should exist for systems with
 other package managers. Please refer to the `OpenOCD Documentation
 <https://openocd.org/>`_ for more recent installation steps.
 
-.. code-block:: bash
+.. prompt:: bash
 
-  $ # Check the packages to be installed: needs deb-src in sources.list
-  $ sudo apt build-dep openocd
-  $ # The following list is NOT complete - please check the latest
-  $ sudo apt-get install libtool pkg-config texinfo libusb-dev \
+  # Check the packages to be installed: needs deb-src in sources.list
+  sudo apt build-dep openocd
+  # The following list is NOT complete - please check the latest
+  sudo apt-get install libtool pkg-config texinfo libusb-dev \
     libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
-  $ git clone https://github.com/openocd-org/openocd.git openocd
-  $ cd openocd
-  $ git submodule init
-  $ git submodule update
-  $ ./bootstrap
-  $ ./configure --prefix=/usr/local/
-  $ make -j`nproc`
-  $ sudo make install
+  git clone https://github.com/openocd-org/openocd.git openocd
+  cd openocd
+  git submodule init
+  git submodule update
+  ./bootstrap
+  ./configure --prefix=/usr/local/
+  make -j`nproc`
+  sudo make install
 
 .. note::
 
@@ -594,28 +596,28 @@ The step is not necessary if the distribution supports the OpenOCD, but
 if building from a source, ensure that the udev rules are installed
 correctly to ensure a sane system.
 
-.. code-block:: bash
+.. prompt:: bash
 
   # Go to the OpenOCD source directory
-  $ cd openocd
-  # Copy the udev rules to the correct system location
-  $ sudo cp ./contrib/60-openocd.rules \
+  cd openocd
+  Copy the udev rules to the correct system location
+  sudo cp ./contrib/60-openocd.rules \
       ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \
       /etc/udev/rules.d/
   # Get Udev to load the new rules up
-  $ sudo udevadm control --reload-rules
+  sudo udevadm control --reload-rules
   # Use the new rules on existing connected devices
-  $ sudo udevadm trigger
+  sudo udevadm trigger
 
 Step 2: Setup GDB
 ^^^^^^^^^^^^^^^^^
 
 Most systems come with gdb-multiarch package.
 
-.. code-block:: bash
+.. prompt:: bash
 
   # Install gdb-multiarch package
-  $ sudo apt-get install gdb-multiarch
+  sudo apt-get install gdb-multiarch
 
 Though using GDB natively is normal, developers with interest in using IDE
 may find a few of these interesting:
@@ -828,7 +830,7 @@ Startup OpenOCD to debug the platform as follows:
 
 .. k3_rst_include_start_openocd_cfg_XDS110
 
-.. code-block:: bash
+.. prompt:: bash
 
   openocd -f board/{board_of_choice}.cfg
 
@@ -842,7 +844,7 @@ Startup OpenOCD to debug the platform as follows:
   <https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59>`_
   to decide if the SoC is supported or not.
 
-.. code-block:: bash
+.. prompt:: bash
 
   openocd -f openocd_connect.cfg
 
@@ -917,7 +919,7 @@ To debug using this server, use GDB directly or your preferred
 GDB-based IDE. To start up GDB in the terminal, run the following
 command.
 
-.. code-block:: bash
+.. prompt:: bash
 
   gdb-multiarch
 
Signature · 1 line
2.40.0
#7 lore raw

Re: [RFC PATCH 2/2] doc: board: ti: k3: Convert to sphinx-prompt

Quoted 211 lines · Nishanth Menon

Sphinx-prompt provides a handy scheme to provide documentation that renders nicely and yet provides a scheme to copy paste for users without having to hand-edit the copied text as is the result of code-block

[1] https://lore.kernel.org/all/[email protected]/

---
  doc/board/ti/k3.rst | 112 ++++++++++++++++++++++----------------------
  1 file changed, 57 insertions(+), 55 deletions(-)
doc/board/ti/k3.rst +51 -49
index 1175b776ad48..ec447358ac39 100644
@@ -194,13 +194,13 @@ All of that to say you will need both a 32bit and 64bit cross compiler
  .. k3_rst_include_end_common_env_vars_desc
 
  .. k3_rst_include_start_common_env_vars_defn
-.. code-block:: bash
+.. prompt:: bash
 
- $ export CC32=arm-linux-gnueabihf-
- $ export CC64=aarch64-linux-gnu-
- $ export LNX_FW_PATH=path/to/ti-linux-firmware
- $ export TFA_PATH=path/to/trusted-firmware-a
- $ export OPTEE_PATH=path/to/optee_os
+ export CC32=arm-linux-gnueabihf-
+ export CC64=aarch64-linux-gnu-
+ export LNX_FW_PATH=path/to/ti-linux-firmware
+ export TFA_PATH=path/to/trusted-firmware-a
+ export OPTEE_PATH=path/to/optee_os
  .. k3_rst_include_end_common_env_vars_defn
 
  We will also need some common environment variables set up for the various
@@ -244,11 +244,11 @@ Building tiboot3.bin
     uses the split binary flow)
 
  .. k3_rst_include_start_build_steps_spl_r5
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXR
- $ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
+ # inside u-boot source
+ make $UBOOT_CFG_CORTEXR
+ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
  .. k3_rst_include_end_build_steps_spl_r5
 
  At this point you should have all the needed binaries to boot the wakeup
@@ -280,11 +280,11 @@ firmware if your device using a split firmware.
     application cores on the main domain.
 
  .. k3_rst_include_start_build_steps_tfa
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside trusted-firmware-a source
- $ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
-        TARGET_BOARD=$TFA_BOARD
+ # inside trusted-firmware-a source
+ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
+      TARGET_BOARD=$TFA_BOARD
  .. k3_rst_include_end_build_steps_tfa
 
  Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD
@@ -296,11 +296,11 @@ use the `lite` option.
     using the TrustZone technology built into the core.
 
  .. k3_rst_include_start_build_steps_optee
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside optee_os source
- $ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
-         PLATFORM=$OPTEE_PLATFORM
+ # inside optee_os source
+ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
+       PLATFORM=$OPTEE_PLATFORM
  .. k3_rst_include_end_build_steps_optee
 
  4. Finally, after TF-A has initialized the main domain and OP-TEE has
@@ -308,11 +308,11 @@ use the `lite` option.
     64bit core in the main domain.
 
  .. k3_rst_include_start_build_steps_uboot
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXA
- $ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
+ # inside u-boot source
+ make $UBOOT_CFG_CORTEXA
+ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
          BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \
          TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin
  .. k3_rst_include_end_build_steps_uboot
@@ -407,14 +407,14 @@ and the same can be extended to other platforms
    be passing to mkimage for signing the fitImage and embedding the key in
    the u-boot dtb.
 
-  .. code-block:: bash
+  .. prompt:: bash
 
      mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
      $UBOOT_PATH/build/a72/dts/dt.dtb
 
    For signing a secondary platform, pass the -K parameter to that DTB
 
-  .. code-block:: bash
+  .. prompt:: bash
 
      mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
      $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb
@@ -473,10 +473,11 @@ then the saveenv command and can be used across various bootmodes too.
 
  **Writing to MMC/EMMC**
 
-.. code-block::
+.. prompt:: bash
+  :prompts: =>
 
-  => env export -t $loadaddr <list of variables>
-  => fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
+  env export -t $loadaddr <list of variables>
+  fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
 
  **Reading from MMC/EMMC**
 
@@ -486,10 +487,11 @@ mmcdev) and set the environments.
  If manually needs to be done then the environment can be read from the
  filesystem and then imported
 
-.. code-block::
+.. prompt:: bash
+  :prompts: =>
 
-  => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
-  => env import -t ${loadaddr} ${filesize}
+  fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
+  env import -t ${loadaddr} ${filesize}
 
  .. _k3_rst_refer_openocd:
 
@@ -546,7 +548,7 @@ Refer to the release notes corresponding to the `OpenOCD version
    box support by OpenOCD. The board-specific documentation will
    cover the details and any adapter/dongle recommendations.
 
-.. code-block:: bash
+.. prompt:: bash
 
   openocd -v
 
@@ -564,21 +566,21 @@ systems, but equivalent instructions should exist for systems with
  other package managers. Please refer to the `OpenOCD Documentation
  <https://openocd.org/>`_ for more recent installation steps.
 
-.. code-block:: bash
+.. prompt:: bash
 
-  $ # Check the packages to be installed: needs deb-src in sources.list
-  $ sudo apt build-dep openocd
-  $ # The following list is NOT complete - please check the latest
-  $ sudo apt-get install libtool pkg-config texinfo libusb-dev \
+  # Check the packages to be installed: needs deb-src in sources.list
+  sudo apt build-dep openocd
+  # The following list is NOT complete - please check the latest
+  sudo apt-get install libtool pkg-config texinfo libusb-dev \
      libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
-  $ git clone https://github.com/openocd-org/openocd.git openocd
-  $ cd openocd
-  $ git submodule init
-  $ git submodule update
-  $ ./bootstrap
-  $ ./configure --prefix=/usr/local/
-  $ make -j`nproc`
-  $ sudo make install
+  git clone https://github.com/openocd-org/openocd.git openocd
+  cd openocd
+  git submodule init
+  git submodule update
+  ./bootstrap
+  ./configure --prefix=/usr/local/
+  make -j`nproc`
+  sudo make install
 
  .. note::
 
@@ -594,28 +596,28 @@ The step is not necessary if the distribution supports the OpenOCD, but
  if building from a source, ensure that the udev rules are installed
  correctly to ensure a sane system.
 
-.. code-block:: bash
+.. prompt:: bash
 
    # Go to the OpenOCD source directory
-  $ cd openocd
-  # Copy the udev rules to the correct system location
-  $ sudo cp ./contrib/60-openocd.rules \
+  cd openocd
+  Copy the udev rules to the correct system location
+  sudo cp ./contrib/60-openocd.rules \
        ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \
        /etc/udev/rules.d/
    # Get Udev to load the new rules up
-  $ sudo udevadm control --reload-rules
+  sudo udevadm control --reload-rules
    # Use the new rules on existing connected devices

doc/board/ti/k3.rst The step is not necessary if the distribution supports the OpenOCD, but · line 617

Quoted 10 lines
doc/board/ti/k3.rst +2 -2
-  $ sudo udevadm trigger
+  sudo udevadm trigger
 
  Step 2: Setup GDB
  ^^^^^^^^^^^^^^^^^
 
  Most systems come with gdb-multiarch package.
 
-.. code-block:: bash
+.. prompt:: bash

.. prompt:: bash $
will enforce $ as prompt?

Cf.
http://sbrunner.github.io/sphinx-prompt/

Best regards

Heinrich

Quoted 34 lines
doc/board/ti/k3.rst +4 -4
    # Install gdb-multiarch package
-  $ sudo apt-get install gdb-multiarch
+  sudo apt-get install gdb-multiarch
 
  Though using GDB natively is normal, developers with interest in using IDE
  may find a few of these interesting:
@@ -828,7 +830,7 @@ Startup OpenOCD to debug the platform as follows:
 
  .. k3_rst_include_start_openocd_cfg_XDS110
 
-.. code-block:: bash
+.. prompt:: bash
 
    openocd -f board/{board_of_choice}.cfg
 
@@ -842,7 +844,7 @@ Startup OpenOCD to debug the platform as follows:
    <https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59>`_
    to decide if the SoC is supported or not.
 
-.. code-block:: bash
+.. prompt:: bash
 
    openocd -f openocd_connect.cfg
 
@@ -917,7 +919,7 @@ To debug using this server, use GDB directly or your preferred
  GDB-based IDE. To start up GDB in the terminal, run the following
  command.
 
-.. code-block:: bash
+.. prompt:: bash
 
    gdb-multiarch
 
#8 lore raw

Re: [RFC PATCH 2/2] doc: board: ti: k3: Convert to sphinx-prompt

On 17:50-20230824, Heinrich Schuchardt wrote:
[...]

Quoted 6 lines

.. prompt:: bash $
will enforce $ as prompt?

Cf.
http://sbrunner.github.io/sphinx-prompt/

Yes, that works great.

Signature · 3 lines
Regards,
Nishanth Menon
Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3  1A34 DDB5 849D 1736 249D
Reviewed-by on v1 2/2
#9 lore raw

Re: [RFC PATCH 2/2] doc: board: ti: k3: Convert to sphinx-prompt

In reply to Nishanth Menon
Quoted 8 lines · Nishanth Menon

Sphinx-prompt provides a handy scheme to provide documentation that renders nicely and yet provides a scheme to copy paste for users without having to hand-edit the copied text as is the result of code-block

[1] https://lore.kernel.org/all/[email protected]/

Reviewed-by on v1 2/2
#10 lore raw

Re: [RFC PATCH 2/2] doc: board: ti: k3: Convert to sphinx-prompt

In reply to Nishanth Menon
Quoted 8 lines · Nishanth Menon

Sphinx-prompt provides a handy scheme to provide documentation that renders nicely and yet provides a scheme to copy paste for users without having to hand-edit the copied text as is the result of code-block

[1] https://lore.kernel.org/all/[email protected]/

Small nitpick below, which is probably a matter of preference

Quoted 110 lines
---
 doc/board/ti/k3.rst | 112 ++++++++++++++++++++++----------------------
 1 file changed, 57 insertions(+), 55 deletions(-)
doc/board/ti/k3.rst +24 -24
index 1175b776ad48..ec447358ac39 100644
@@ -194,13 +194,13 @@ All of that to say you will need both a 32bit and 64bit cross compiler
 .. k3_rst_include_end_common_env_vars_desc
 
 .. k3_rst_include_start_common_env_vars_defn
-.. code-block:: bash
+.. prompt:: bash
 
- $ export CC32=arm-linux-gnueabihf-
- $ export CC64=aarch64-linux-gnu-
- $ export LNX_FW_PATH=path/to/ti-linux-firmware
- $ export TFA_PATH=path/to/trusted-firmware-a
- $ export OPTEE_PATH=path/to/optee_os
+ export CC32=arm-linux-gnueabihf-
+ export CC64=aarch64-linux-gnu-
+ export LNX_FW_PATH=path/to/ti-linux-firmware
+ export TFA_PATH=path/to/trusted-firmware-a
+ export OPTEE_PATH=path/to/optee_os
 .. k3_rst_include_end_common_env_vars_defn
 
 We will also need some common environment variables set up for the various
@@ -244,11 +244,11 @@ Building tiboot3.bin
    uses the split binary flow)
 
 .. k3_rst_include_start_build_steps_spl_r5
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXR
- $ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
+ # inside u-boot source
+ make $UBOOT_CFG_CORTEXR
+ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
 .. k3_rst_include_end_build_steps_spl_r5
 
 At this point you should have all the needed binaries to boot the wakeup
@@ -280,11 +280,11 @@ firmware if your device using a split firmware.
    application cores on the main domain.
 
 .. k3_rst_include_start_build_steps_tfa
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside trusted-firmware-a source
- $ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
-        TARGET_BOARD=$TFA_BOARD
+ # inside trusted-firmware-a source
+ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
+      TARGET_BOARD=$TFA_BOARD
 .. k3_rst_include_end_build_steps_tfa
 
 Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD
@@ -296,11 +296,11 @@ use the `lite` option.
    using the TrustZone technology built into the core.
 
 .. k3_rst_include_start_build_steps_optee
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside optee_os source
- $ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
-         PLATFORM=$OPTEE_PLATFORM
+ # inside optee_os source
+ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
+       PLATFORM=$OPTEE_PLATFORM
 .. k3_rst_include_end_build_steps_optee
 
 4. Finally, after TF-A has initialized the main domain and OP-TEE has
@@ -308,11 +308,11 @@ use the `lite` option.
    64bit core in the main domain.
 
 .. k3_rst_include_start_build_steps_uboot
-.. code-block:: bash
+.. prompt:: bash
 
- $ # inside u-boot source
- $ make $UBOOT_CFG_CORTEXA
- $ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
+ # inside u-boot source
+ make $UBOOT_CFG_CORTEXA
+ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
         BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \
         TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin
 .. k3_rst_include_end_build_steps_uboot
@@ -407,14 +407,14 @@ and the same can be extended to other platforms
   be passing to mkimage for signing the fitImage and embedding the key in
   the u-boot dtb.
 
-  .. code-block:: bash
+  .. prompt:: bash
 
     mkimage -r -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
     $UBOOT_PATH/build/a72/dts/dt.dtb
 
   For signing a secondary platform, pass the -K parameter to that DTB
 
-  .. code-block:: bash
+  .. prompt:: bash
 
     mkimage -f fitImage.its -k $UBOOT_PATH/board/ti/keys -K
     $UBOOT_PATH/build/a72/arch/arm/dts/k3-j721e-sk.dtb

doc/board/ti/k3.rst then the saveenv command and can be used across various bootmodes too. · line 477

Quoted 6 lines
doc/board/ti/k3.rst +2 -1
@@ -473,10 +473,11 @@ then the saveenv command and can be used across various bootmodes too.
 
 **Writing to MMC/EMMC**
 
-.. code-block::
+.. prompt:: bash
+  :prompts: =>

nitpick: This can be a one-liner by using the "prompts" positional argument

.. prompt:: bash =>

Quoted 9 lines
doc/board/ti/k3.rst +2 -2
-  => env export -t $loadaddr <list of variables>
-  => fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
+  env export -t $loadaddr <list of variables>
+  fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
 
 **Reading from MMC/EMMC**
 

doc/board/ti/k3.rst mmcdev) and set the environments. · line 491

Quoted 6 lines
doc/board/ti/k3.rst +2 -1
@@ -486,10 +487,11 @@ mmcdev) and set the environments.
 If manually needs to be done then the environment can be read from the
 filesystem and then imported
 
-.. code-block::
+.. prompt:: bash
+  :prompts: =>

nitpick: Same here

Quoted 118 lines
doc/board/ti/k3.rst +27 -27
-  => fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
-  => env import -t ${loadaddr} ${filesize}
+  fatload mmc ${mmcdev} ${loadaddr} ${bootenvfile}
+  env import -t ${loadaddr} ${filesize}
 
 .. _k3_rst_refer_openocd:
 
@@ -546,7 +548,7 @@ Refer to the release notes corresponding to the `OpenOCD version
   box support by OpenOCD. The board-specific documentation will
   cover the details and any adapter/dongle recommendations.
 
-.. code-block:: bash
+.. prompt:: bash
 
  openocd -v
 
@@ -564,21 +566,21 @@ systems, but equivalent instructions should exist for systems with
 other package managers. Please refer to the `OpenOCD Documentation
 <https://openocd.org/>`_ for more recent installation steps.
 
-.. code-block:: bash
+.. prompt:: bash
 
-  $ # Check the packages to be installed: needs deb-src in sources.list
-  $ sudo apt build-dep openocd
-  $ # The following list is NOT complete - please check the latest
-  $ sudo apt-get install libtool pkg-config texinfo libusb-dev \
+  # Check the packages to be installed: needs deb-src in sources.list
+  sudo apt build-dep openocd
+  # The following list is NOT complete - please check the latest
+  sudo apt-get install libtool pkg-config texinfo libusb-dev \
     libusb-1.0.0-dev libftdi-dev libhidapi-dev autoconf automake
-  $ git clone https://github.com/openocd-org/openocd.git openocd
-  $ cd openocd
-  $ git submodule init
-  $ git submodule update
-  $ ./bootstrap
-  $ ./configure --prefix=/usr/local/
-  $ make -j`nproc`
-  $ sudo make install
+  git clone https://github.com/openocd-org/openocd.git openocd
+  cd openocd
+  git submodule init
+  git submodule update
+  ./bootstrap
+  ./configure --prefix=/usr/local/
+  make -j`nproc`
+  sudo make install
 
 .. note::
 
@@ -594,28 +596,28 @@ The step is not necessary if the distribution supports the OpenOCD, but
 if building from a source, ensure that the udev rules are installed
 correctly to ensure a sane system.
 
-.. code-block:: bash
+.. prompt:: bash
 
   # Go to the OpenOCD source directory
-  $ cd openocd
-  # Copy the udev rules to the correct system location
-  $ sudo cp ./contrib/60-openocd.rules \
+  cd openocd
+  Copy the udev rules to the correct system location
+  sudo cp ./contrib/60-openocd.rules \
       ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \
       /etc/udev/rules.d/
   # Get Udev to load the new rules up
-  $ sudo udevadm control --reload-rules
+  sudo udevadm control --reload-rules
   # Use the new rules on existing connected devices
-  $ sudo udevadm trigger
+  sudo udevadm trigger
 
 Step 2: Setup GDB
 ^^^^^^^^^^^^^^^^^
 
 Most systems come with gdb-multiarch package.
 
-.. code-block:: bash
+.. prompt:: bash
 
   # Install gdb-multiarch package
-  $ sudo apt-get install gdb-multiarch
+  sudo apt-get install gdb-multiarch
 
 Though using GDB natively is normal, developers with interest in using IDE
 may find a few of these interesting:
@@ -828,7 +830,7 @@ Startup OpenOCD to debug the platform as follows:
 
 .. k3_rst_include_start_openocd_cfg_XDS110
 
-.. code-block:: bash
+.. prompt:: bash
 
   openocd -f board/{board_of_choice}.cfg
 
@@ -842,7 +844,7 @@ Startup OpenOCD to debug the platform as follows:
   <https://github.com/openocd-org/openocd/blob/master/tcl/target/ti_k3.cfg#L59>`_
   to decide if the SoC is supported or not.
 
-.. code-block:: bash
+.. prompt:: bash
 
   openocd -f openocd_connect.cfg
 
@@ -917,7 +919,7 @@ To debug using this server, use GDB directly or your preferred
 GDB-based IDE. To start up GDB in the terminal, run the following
 command.
 
-.. code-block:: bash
+.. prompt:: bash
 
   gdb-multiarch
 
Signature · 1 line
2.40.0
#11 lore raw

Re: [RFC PATCH 2/2] doc: board: ti: k3: Convert to sphinx-prompt

On 10:07-20230828, Mattijs Korpershoek wrote:
[...]

Quoted 21 lines
Quoted 3 lines

-.. code-block::
+.. prompt:: bash
+ :prompts: =>

nitpick: This can be a one-liner by using the "prompts" positional argument

.. prompt:: bash =>

Quoted 12 lines
doc/board/ti/k3.rst +2 -2
-  => env export -t $loadaddr <list of variables>
-  => fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
+  env export -t $loadaddr <list of variables>
+  fatwrite mmc ${mmcdev} ${loadaddr} ${bootenvfile} ${filesize}
 
 **Reading from MMC/EMMC**
@@ -486,10 +487,11 @@ mmcdev) and set the environments.
 If manually needs to be done then the environment can be read from the
 filesystem and then imported
 
Quoted 5 lines

doc/board/ti/k3.rst then the saveenv command and can be used across various bootmodes too. · line 477

Quoted 3 lines
doc/board/ti/k3.rst +2 -1
-.. code-block::
+.. prompt:: bash
+  :prompts: =>

nitpick: Same here

Thanks for catching, will fixup in a follow on series.

Signature · 3 lines
Regards,
Nishanth Menon
Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3  1A34 DDB5 849D 1736 249D