Re: [PATCH] docs/can: convert to restructuredText

[Thomas Huth <thuth@redhat.com>]

On 17/12/2021 22.21, oxr463@gmx.us wrote:
> From: Lucas Ramage <lucas.ramage@infinite-omicron.com>

  Hi!

Thanks for your patch! This looks like a good idea, but I think there are 
some minor issues which should be fixed...

First: Please check your mailer setup. The mail has been sent via @gmx.us, 
but the Signed-off-by uses @infinite-omicron.com ... not a big issue, I 
guess, but it might be better to use the same address for both.

Second, it does not work here, at least not with Sphinx 1.7 which I have 
installed on my system:

  docs/can.rst:39:Enumerated list ends without a blank line;
  unexpected unindent.

Does this render correctly on your system?

Also there are paragraphs in this file which should be clearly marked as 
pre-formatted text (use "::" for those), e.g.:

diff --git a/docs/can.rst b/docs/can.rst
--- a/docs/can.rst
+++ b/docs/can.rst
@@ -122,7 +125,7 @@ is setup according to the previous SJA1000 section.
      -device ctucan_pci,canbus0=canbus0-bus,canbus1=canbus0-bus \
      -nographic

-Setup of CTU CAN FD controller in a guest Linux system
+Setup of CTU CAN FD controller in a guest Linux system::

    insmod ctucanfd.ko || modprobe ctucanfd
    insmod ctucanfd_pci.ko || modprobe ctucanfd_pci

> Bug: https://gitlab.com/qemu-project/qemu/-/issues/527

Please use "Buglink:" instead, it's more common in the QEMU project.

> Signed-off-by: Lucas Ramage <lucas.ramage@infinite-omicron.com>
> ---
>   docs/{can.txt => can.rst} | 14 ++++++--------

While you're at it, I think this file should be moved into one of the 
subfolders as well, likely docs/system/ I guess.

>   docs/index.rst            |  1 +
>   2 files changed, 7 insertions(+), 8 deletions(-)
>   rename docs/{can.txt => can.rst} (97%)
> 
> diff --git a/docs/can.txt b/docs/can.rst
> similarity index 97%
> rename from docs/can.txt
> rename to docs/can.rst
> index 0d310237df..995134d079 100644
> --- a/docs/can.txt
> +++ b/docs/can.rst
[...]
> @@ -196,3 +193,4 @@ Links to other resources
>        http://canbus.pages.fel.cvut.cz/ctucanfd_ip_core/driver_doc/ctucanfd-driver.html
>    (11) Integration with PCIe interfacing for Intel/Altera Cyclone IV based board
>        https://gitlab.fel.cvut.cz/canbus/pcie-ctu_can_fd
> +

This look like an unnecessary addition of an empty line.

> diff --git a/docs/index.rst b/docs/index.rst
> index 0b9ee9901d..beb868ca7f 100644
> --- a/docs/index.rst
> +++ b/docs/index.rst
> @@ -18,3 +18,4 @@ Welcome to QEMU's documentation!
>      interop/index
>      specs/index
>      devel/index
> +   can
> --
> 2.32.0
> 
> 

  Thomas