[PATCH] drm/doc: use proper cross-references for sections

[PATCH] drm/doc: use proper cross-references for sections

[Simon Ser]

When I originally wrote these docs, I couldn't manage to insert a
cross-reference to a section. Here's how it can be done.

Signed-off-by: Simon Ser <contact@emersion.fr>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Pekka Paalanen <pekka.paalanen@collabora.com>
---
 Documentation/gpu/drm-kms.rst | 2 ++
 Documentation/gpu/drm-mm.rst  | 2 ++
 include/uapi/drm/drm.h        | 9 ++++-----
 3 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index c92d425cb2dd..ca9210e47266 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -360,6 +360,8 @@ Format Functions Reference
 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
    :export:
 
+.. _kms_dumb_buffer_objects:
+
 Dumb Buffer Objects
 ===================
 
diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index 3d5dc9dc1bfe..513197359aba 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -517,6 +517,8 @@ DRM Cache Handling and Fast WC memcpy()
 .. kernel-doc:: drivers/gpu/drm/drm_cache.c
    :export:
 
+.. _drm_sync_objects:
+
 DRM Sync Objects
 ===========================
 
diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h
index 863e47200911..75ec985d95e5 100644
--- a/include/uapi/drm/drm.h
+++ b/include/uapi/drm/drm.h
@@ -673,8 +673,8 @@ struct drm_gem_open {
  * Bitfield of supported PRIME sharing capabilities. See &DRM_PRIME_CAP_IMPORT
  * and &DRM_PRIME_CAP_EXPORT.
  *
- * PRIME buffers are exposed as dma-buf file descriptors. See
- * Documentation/gpu/drm-mm.rst, section "PRIME Buffer Sharing".
+ * PRIME buffers are exposed as dma-buf file descriptors.
+ * See :ref:`prime_buffer_sharing`.
  */
 #define DRM_CAP_PRIME			0x5
 /**
@@ -756,15 +756,14 @@ struct drm_gem_open {
 /**
  * DRM_CAP_SYNCOBJ
  *
- * If set to 1, the driver supports sync objects. See
- * Documentation/gpu/drm-mm.rst, section "DRM Sync Objects".
+ * If set to 1, the driver supports sync objects. See :ref:`drm_sync_objects`.
  */
 #define DRM_CAP_SYNCOBJ		0x13
 /**
  * DRM_CAP_SYNCOBJ_TIMELINE
  *
  * If set to 1, the driver supports timeline operations on sync objects. See
- * Documentation/gpu/drm-mm.rst, section "DRM Sync Objects".
+ * :ref:`drm_sync_objects`.
  */
 #define DRM_CAP_SYNCOBJ_TIMELINE	0x14
 
-- 
2.41.0

Re: [PATCH] drm/doc: use proper cross-references for sections

[Daniel Vetter]

On Thu, 3 Aug 2023 at 11:57, Simon Ser <contact@emersion.fr> wrote:
>
> When I originally wrote these docs, I couldn't manage to insert a
> cross-reference to a section. Here's how it can be done.
>
> Signed-off-by: Simon Ser <contact@emersion.fr>
> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
> Cc: Pekka Paalanen <pekka.paalanen@collabora.com>

Acked-by: me

> ---
>  Documentation/gpu/drm-kms.rst | 2 ++
>  Documentation/gpu/drm-mm.rst  | 2 ++
>  include/uapi/drm/drm.h        | 9 ++++-----
>  3 files changed, 8 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index c92d425cb2dd..ca9210e47266 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -360,6 +360,8 @@ Format Functions Reference
>  .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
>     :export:
>
> +.. _kms_dumb_buffer_objects:
> +
>  Dumb Buffer Objects
>  ===================
>
> diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> index 3d5dc9dc1bfe..513197359aba 100644
> --- a/Documentation/gpu/drm-mm.rst
> +++ b/Documentation/gpu/drm-mm.rst
> @@ -517,6 +517,8 @@ DRM Cache Handling and Fast WC memcpy()
>  .. kernel-doc:: drivers/gpu/drm/drm_cache.c
>     :export:
>
> +.. _drm_sync_objects:
> +
>  DRM Sync Objects
>  ===========================
>
> diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h
> index 863e47200911..75ec985d95e5 100644
> --- a/include/uapi/drm/drm.h
> +++ b/include/uapi/drm/drm.h
> @@ -673,8 +673,8 @@ struct drm_gem_open {
>   * Bitfield of supported PRIME sharing capabilities. See &DRM_PRIME_CAP_IMPORT
>   * and &DRM_PRIME_CAP_EXPORT.
>   *
> - * PRIME buffers are exposed as dma-buf file descriptors. See
> - * Documentation/gpu/drm-mm.rst, section "PRIME Buffer Sharing".
> + * PRIME buffers are exposed as dma-buf file descriptors.
> + * See :ref:`prime_buffer_sharing`.
>   */
>  #define DRM_CAP_PRIME                  0x5
>  /**
> @@ -756,15 +756,14 @@ struct drm_gem_open {
>  /**
>   * DRM_CAP_SYNCOBJ
>   *
> - * If set to 1, the driver supports sync objects. See
> - * Documentation/gpu/drm-mm.rst, section "DRM Sync Objects".
> + * If set to 1, the driver supports sync objects. See :ref:`drm_sync_objects`.
>   */
>  #define DRM_CAP_SYNCOBJ                0x13
>  /**
>   * DRM_CAP_SYNCOBJ_TIMELINE
>   *
>   * If set to 1, the driver supports timeline operations on sync objects. See
> - * Documentation/gpu/drm-mm.rst, section "DRM Sync Objects".
> + * :ref:`drm_sync_objects`.
>   */
>  #define DRM_CAP_SYNCOBJ_TIMELINE       0x14
>
> --
> 2.41.0
>
>


-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Re: [PATCH] drm/doc: use proper cross-references for sections

[Jani Nikula]

On Thu, 03 Aug 2023, Simon Ser <contact@emersion.fr> wrote:
> When I originally wrote these docs, I couldn't manage to insert a
> cross-reference to a section. Here's how it can be done.
>
> Signed-off-by: Simon Ser <contact@emersion.fr>
> Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
> Cc: Pekka Paalanen <pekka.paalanen@collabora.com>
> ---
>  Documentation/gpu/drm-kms.rst | 2 ++
>  Documentation/gpu/drm-mm.rst  | 2 ++
>  include/uapi/drm/drm.h        | 9 ++++-----
>  3 files changed, 8 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index c92d425cb2dd..ca9210e47266 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -360,6 +360,8 @@ Format Functions Reference
>  .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
>     :export:
>  
> +.. _kms_dumb_buffer_objects:
> +
>  Dumb Buffer Objects
>  ===================
>  
> diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> index 3d5dc9dc1bfe..513197359aba 100644
> --- a/Documentation/gpu/drm-mm.rst
> +++ b/Documentation/gpu/drm-mm.rst
> @@ -517,6 +517,8 @@ DRM Cache Handling and Fast WC memcpy()
>  .. kernel-doc:: drivers/gpu/drm/drm_cache.c
>     :export:
>  
> +.. _drm_sync_objects:
> +
>  DRM Sync Objects
>  ===========================

Care to fix that title underline too, in a separate patch, please?

This one's

Reviewed-by: Jani Nikula <jani.nikula@intel.com>


>  
> diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h
> index 863e47200911..75ec985d95e5 100644
> --- a/include/uapi/drm/drm.h
> +++ b/include/uapi/drm/drm.h
> @@ -673,8 +673,8 @@ struct drm_gem_open {
>   * Bitfield of supported PRIME sharing capabilities. See &DRM_PRIME_CAP_IMPORT
>   * and &DRM_PRIME_CAP_EXPORT.
>   *
> - * PRIME buffers are exposed as dma-buf file descriptors. See
> - * Documentation/gpu/drm-mm.rst, section "PRIME Buffer Sharing".
> + * PRIME buffers are exposed as dma-buf file descriptors.
> + * See :ref:`prime_buffer_sharing`.
>   */
>  #define DRM_CAP_PRIME			0x5
>  /**
> @@ -756,15 +756,14 @@ struct drm_gem_open {
>  /**
>   * DRM_CAP_SYNCOBJ
>   *
> - * If set to 1, the driver supports sync objects. See
> - * Documentation/gpu/drm-mm.rst, section "DRM Sync Objects".
> + * If set to 1, the driver supports sync objects. See :ref:`drm_sync_objects`.
>   */
>  #define DRM_CAP_SYNCOBJ		0x13
>  /**
>   * DRM_CAP_SYNCOBJ_TIMELINE
>   *
>   * If set to 1, the driver supports timeline operations on sync objects. See
> - * Documentation/gpu/drm-mm.rst, section "DRM Sync Objects".
> + * :ref:`drm_sync_objects`.
>   */
>  #define DRM_CAP_SYNCOBJ_TIMELINE	0x14

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] drm/doc: use proper cross-references for sections

[Simon Ser]

On Thursday, August 3rd, 2023 at 12:07, Jani Nikula <jani.nikula@linux.intel.com> wrote:

> > DRM Sync Objects
> > ===========================
> 
> Care to fix that title underline too, in a separate patch, please?

Sure, submitted!

> This one's
> 
> Reviewed-by: Jani Nikula <jani.nikula@intel.com>

Thank you!