drm/i915: Add missing docbook chapters for i915 uapi.
Subsystems (3)
Maarten Lankhorst
maintainerPATCH v2 1/1 drm/i915: Add missing docbook chapters for i915 uapi.
I noticed when grepping for DOC: that those were defined in the header, but not actually used. Fix it by removing all chapters and the internal annotation, so the docbook generated chapters are used.
Changes since v1:
- Just remove the chapters, no need for those.
--- Documentation/gpu/driver-uapi.rst | 21 --------------------- 1 file changed, 21 deletions(-)
Documentation/gpu/driver-uapi.rst +0 -21
@@ -5,25 +5,4 @@ DRM Driver uAPI drm/i915 uAPI ============= -Engine Discovery uAPI ---------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Engine Discovery uAPI - -Context Engine Map uAPI ------------------------ - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Context Engine Map uAPI - -Virtual Engine uAPI -------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Virtual Engine uAPI - -i915_drm.h ----------- .. kernel-doc:: include/uapi/drm/i915_drm.h - :internal:
Signature · 6 lines
2.31.0 _______________________________________________ Intel-gfx mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Quoted 11 lines · Maarten Lankhorst
I noticed when grepping for DOC: that those were defined in the header, but not actually used. Fix it by removing all chapters and the internal annotation, so the docbook generated chapters are used.
Changes since v1:
- Just remove the chapters, no need for those.
Indeed, it seems to still render correctly here.
Maybe update the commit title when pushing,
Quoted 37 lines
--- Documentation/gpu/driver-uapi.rst | 21 --------------------- 1 file changed, 21 deletions(-)Documentation/gpu/driver-uapi.rst +0
-22@@ -5,25 +5,4 @@ DRM Driver uAPI drm/i915 uAPI ============= -Engine Discovery uAPI ---------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Engine Discovery uAPI - -Context Engine Map uAPI ------------------------ - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Context Engine Map uAPI - -Virtual Engine uAPI -------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Virtual Engine uAPI - -i915_drm.h ----------- .. kernel-doc:: include/uapi/drm/i915_drm.h - :internal: --2.31.0
Quoted 4 lines
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Maarten Lankhorst
maintainerOp 15-07-2021 om 14:19 schreef Matthew Auld:
Quoted 54 lines
Quoted 10 lines · Maarten Lankhorst
I noticed when grepping for DOC: that those were defined in the header, but not actually used. Fix it by removing all chapters and the internal annotation, so the docbook generated chapters are used.
Changes since v1:
- Just remove the chapters, no need for those.Indeed, it seems to still render correctly here.
Maybe update the commit title when pushing,
Reviewed-by Matthew Auld <[email protected]>Quoted 37 lines
--- Documentation/gpu/driver-uapi.rst | 21 --------------------- 1 file changed, 21 deletions(-)Documentation/gpu/driver-uapi.rst +0
-22@@ -5,25 +5,4 @@ DRM Driver uAPI drm/i915 uAPI ============= -Engine Discovery uAPI ---------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Engine Discovery uAPI - -Context Engine Map uAPI ------------------------ - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Context Engine Map uAPI - -Virtual Engine uAPI -------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Virtual Engine uAPI - -i915_drm.h ----------- .. kernel-doc:: include/uapi/drm/i915_drm.h - :internal: --2.31.0
Quoted 4 lines
Quoted 4 lines
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Thanks, pushed!
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Quoted 30 lines · Maarten Lankhorst
I noticed when grepping for DOC: that those were defined in the header, but not actually used. Fix it by removing all chapters and the internal annotation, so the docbook generated chapters are used.
Changes since v1:
- Just remove the chapters, no need for those.Signed-off-by Maarten Lankhorst <[email protected]>--- Documentation/gpu/driver-uapi.rst | 21 --------------------- 1 file changed, 21 deletions(-)Documentation/gpu/driver-uapi.rst +0
-8@@ -5,25 +5,4 @@ DRM Driver uAPI drm/i915 uAPI ============= -Engine Discovery uAPI ---------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Engine Discovery uAPI - -Context Engine Map uAPI ------------------------
Documentation/gpu/driver-uapi.rst DRM Driver uAPI · line 25
Quoted 10 lines
Documentation/gpu/driver-uapi.rst +0
-10- -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Context Engine Map uAPI - -Virtual Engine uAPI -------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Virtual Engine uAPI -
Hmm my idea was to have the above three laid out sequentially in the doc so the narrative makes sense. Otherwise they are at random locations in i915_drm.h so reader cannot get the nice story around high level operation and interactions between then. Initially I had this narrative right in this file but Daniel wanted it moved into i915_drm.h.
I didn't really understand the commit message to understand what wasn't right?
Documentation/gpu/driver-uapi.rst DRM Driver uAPI · line 29
Quoted 4 lines
Documentation/gpu/driver-uapi.rst +0
-3-i915_drm.h ----------- .. kernel-doc:: include/uapi/drm/i915_drm.h - :internal:
This one I added to avoid duplicate sections. It won't be a problem if they are not referenced from driver-uapi.rst though.
Regards,
Tvrtko
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Maarten Lankhorst
maintainerOp 16-07-2021 om 15:07 schreef Tvrtko Ursulin:
Quoted 44 lines · Maarten Lankhorst
Quoted 29 lines
I noticed when grepping for DOC: that those were defined in the header, but not actually used. Fix it by removing all chapters and the internal annotation, so the docbook generated chapters are used.
Changes since v1:
- Just remove the chapters, no need for those.Signed-off-by Maarten Lankhorst <[email protected]>---
Documentation/gpu/driver-uapi.rst| 21 ---------------------1 file changed, 21 deletions(-)Documentation/gpu/driver-uapi.rst +0
-0@@ -5,25 +5,4 @@ DRM Driver uAPIdrm/i915 uAPI
=============
-Engine Discovery uAPI
----------------------Documentation/gpu/driver-uapi.rst +0
-6- -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Engine Discovery uAPI - -Context Engine Map uAPI ------------------------Documentation/gpu/driver-uapi.rst DRM Driver uAPI · line 25
Quoted 10 lines
Documentation/gpu/driver-uapi.rst +0
-10- -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Context Engine Map uAPI - -Virtual Engine uAPI -------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Virtual Engine uAPI -Hmm my idea was to have the above three laid out sequentially in the doc so the narrative makes sense. Otherwise they are at random locations in
i915_drm.hso reader cannot get the nice story around high level operation and interactions between then. Initially I had this narrative right in this file but Daniel wanted it moved intoi915_drm.h.
Quoted 1 line
I didn't really understand the commit message to understand what wasn't right?
Some chapters went missing, and instead of defining the same chapters in multiple places, I felt we could just revert the change and get it right.
include/uapi/drm/i915_drm.h: * DOC: uevents generated by i915 on it's device node include/uapi/drm/i915_drm.h: * DOC: perf_events exposed by i915 through /sys/bus/event_sources/drivers/i915 include/uapi/drm/i915_drm.h: * DOC: Virtual Engine uAPIinclude/uapi/drm/i915_drm.h: * DOC: Context Engine Map uAPIinclude/uapi/drm/i915_drm.h: * DOC: Engine Discovery uAPI
You added the last 3, but forgot the first 2. Since removing worked, I felt we could just leave it at that. :)
No need to define twice.
Quoted 6 lines
Quoted 4 lines
-i915_drm.h
-----------
.. kernel-doc::include/uapi/drm/i915_drm.h
- :internal:This one I added to avoid duplicate sections. It won't be a problem if they are not referenced from
driver-uapi.rstthough.
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Quoted 49 lines · Maarten Lankhorst
Op 16-07-2021 om 15:07 schreef Tvrtko Ursulin:
Quoted 44 lines · Maarten Lankhorst
Quoted 29 lines
I noticed when grepping for DOC: that those were defined in the header, but not actually used. Fix it by removing all chapters and the internal annotation, so the docbook generated chapters are used.
Changes since v1:
- Just remove the chapters, no need for those.Signed-off-by Maarten Lankhorst <[email protected]>--- Documentation/gpu/driver-uapi.rst | 21 --------------------- 1 file changed, 21 deletions(-)Documentation/gpu/driver-uapi.rst +0
-7@@ -5,25 +5,4 @@ DRM Driver uAPI drm/i915 uAPI ============= -Engine Discovery uAPI ---------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Engine Discovery uAPI - -Context Engine Map uAPI ------------------------Documentation/gpu/driver-uapi.rst DRM Driver uAPI · line 24
Quoted 10 lines
Documentation/gpu/driver-uapi.rst +0
-10- -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Context Engine Map uAPI - -Virtual Engine uAPI -------------------- - -.. kernel-doc:: include/uapi/drm/i915_drm.h - :doc: Virtual Engine uAPI -Hmm my idea was to have the above three laid out sequentially in the doc so the narrative makes sense. Otherwise they are at random locations in
i915_drm.hso reader cannot get the nice story around high level operation and interactions between then. Initially I had this narrative right in this file but Daniel wanted it moved intoi915_drm.h.Quoted 1 line
I didn't really understand the commit message to understand what wasn't right?
Some chapters went missing, and instead of defining the same chapters in multiple places, I felt we could just revert the change and get it right.
Quoted 7 lines
include/uapi/drm/i915_drm.h: * DOC: uevents generated by i915 on it's device nodeinclude/uapi/drm/i915_drm.h: * DOC:perf_eventsexposed by i915 through/sys/bus/event_sources/drivers/i915include/uapi/drm/i915_drm.h: * DOC: Virtual Engine uAPIinclude/uapi/drm/i915_drm.h: * DOC: Context Engine Map uAPIinclude/uapi/drm/i915_drm.h: * DOC: Engine Discovery uAPIYou added the last 3, but forgot the first 2. Since removing worked, I felt we could just leave it at that. :)
Hmm.. I thought the ":internal:" keyword will avoid duplicating chapters which were externally referenced but it seems it's not what it does.
No idea then how to do what I want. Docs are a bit hard to find for some of this. Oh well..
I could pull my chapters back out but Daniel explicitly wanted them in i915_drm.h so I don't see a way to reconcile both mine and his wishes here. So it can stay a bit of a mess.
Regards,
Tvrtko
Quoted 9 lines
No need to define twice.
Quoted 6 lines
Documentation/gpu/driver-uapi.rst DRM Driver uAPI · line 29
Quoted 4 lines
Documentation/gpu/driver-uapi.rst +0
-3-i915_drm.h ----------- .. kernel-doc:: include/uapi/drm/i915_drm.h - :internal:This one I added to avoid duplicate sections. It won't be a problem if they are not referenced from
driver-uapi.rstthough.
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Patchwork
CI[Intel-gfx] ✗ Fi.CI.BAT: failure for drm/i915: Add missing docbook chapters for i915 uapi. (rev2)
In reply to Maarten Lankhorst== Series Details ==
== Series Details ==
Series: drm/i915: Add missing docbook chapters for i915 uapi. (rev2)
URL : https://patchwork.freedesktop.org/series/92359/
State : failure
== Summary ==
Applying: drm/i915: Add missing docbook chapters for i915 uapi. Using index info to reconstruct a base tree...
M Documentation/gpu/driver-uapi.rst
Falling back to patching base and 3-way merge...
No changes -- Patch already applied.
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx