Re: [PATCH v2 2/2] docs: driver-api: virtio: virtio on Linux
From: Ricardo Cañuelo <hidden>
Date: 2022-08-08 09:07:07
Also in:
linux-doc
Hi Bagas, Thanks for reviewing the patch, comments below: On sáb, ago 06 2022 at 14:58:08, Bagas Sanjaya [off-list ref] wrote:
quoted hunk
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 _______________________________________________ Virtualization mailing list Virtualization@lists.linux-foundation.org https://lists.linuxfoundation.org/mailman/listinfo/virtualization