Virtualization - Aug 2022 - [PATCH v2 2/2] docs: driver-api: virtio: virtio on Linux

Hi Bagas,

Thanks for reviewing the patch, comments below:

On s?b, ago 06 2022 at 14:58:08, Bagas Sanjaya <bagasdotme at gmail.com>
wrote:
> Sphinx citation syntax can be used for external references, like:
>
> diff --git a/Documentation/driver-api/virtio/virtio.rst
b/Documentation/driver-api/virtio/virtio.rst
> index 4b73c705c94c61..abd682cfd41eda 100644
> --- a/Documentation/driver-api/virtio/virtio.rst
> +++ b/Documentation/driver-api/virtio/virtio.rst
> @@ -50,8 +50,8 @@ similar to the ones used in a network device:
>  All the buffers the descriptors point to are allocated by the guest and
>  used by the host either for reading or for writing but not for both.
>  
> -Refer to Chapter 2.5 ("Virtqueues") of the virtio spec [1] for
the
> -reference definitions of virtqueues and to [2] for an illustrated
> +Refer to Chapter 2.5 ("Virtqueues") of the virtio spec [1]_ for
the
> +reference definitions of virtqueues and to [2]_ for an illustrated
>  overview of how the host device and the guest driver communicate.
>  
>  The :c:type:`vring_virtqueue` struct models a virtqueue, including the
> @@ -138,13 +138,13 @@ calling a transport-specific ``find_vqs`` method.
>  References
>  =========>  
> -[1] Virtio Spec v1.2:
> -https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
> +.. [1] Virtio Spec v1.2:
> +   https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
>  
> -Check for later versions of the spec as well.
> +   Check for later versions of the spec as well.
>  
> -[2] Virtqueues and virtio ring: How the data travels
> -https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels
> +.. [2] Virtqueues and virtio ring: How the data travels
> +  
https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels
>  
>  .. rubric:: Footnotes
Is that the preferred way to do it? I didn't find any guidelines about
it and the existing docs don't seem to settle on any specific
style. Personally I prefer to keep it as it is in the patch because I
like the bibliography references to look different than footnote links
([] vs superscript).

Cheers,
Ricardo