[PATCH] drm/doc: Switch to sphinx/rst fixed-width quoting

Jani Nikula jani.nikula at linux.intel.com
Wed Jun 1 09:46:33 UTC 2016


On Wed, 01 Jun 2016, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> There's still something very fishy going on with some of these, e.g.
> the drm_modeset_lock Example: and the "Standard GTF Parameters:" Line
> somehow get treated as heading when just appending a :: at the end of
> those lines. But it seems to work everywhere else. Maybe the
> kernel-doc heading generation logic is still a bit wonky?

Try adding a blank line between the line with trailing :: and the actual
preformatted text. Seems to do the right thing for me.

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks

"Blank lines are required before and after a literal block, but these
blank lines are not included as part of the literal block."


BR,
Jani.

> v2: Found more. Also s/\//#/ in the vgpu ascii-art - sphinx treats
> those as comments and switch to variable-width, which wreaks the
> layout.
>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
>  drivers/gpu/drm/drm_bridge.c        |  2 +-
>  drivers/gpu/drm/drm_fb_cma_helper.c |  2 +-
>  drivers/gpu/drm/drm_fops.c          |  2 +-
>  drivers/gpu/drm/drm_modes.c         |  5 ++++-
>  drivers/gpu/drm/drm_modeset_lock.c  |  2 +-
>  drivers/gpu/drm/drm_vma_manager.c   |  3 +++
>  drivers/gpu/drm/i915/i915_reg.h     |  2 +-
>  drivers/gpu/drm/i915/i915_vgpu.c    | 24 ++++++++++++------------
>  include/drm/drm_modes.h             |  2 ++
>  9 files changed, 26 insertions(+), 18 deletions(-)
>
> diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
> index b3654404abd0..255543086590 100644
> --- a/drivers/gpu/drm/drm_bridge.c
> +++ b/drivers/gpu/drm/drm_bridge.c
> @@ -36,7 +36,7 @@
>   * encoder chain.
>   *
>   * A bridge is always attached to a single &drm_encoder at a time, but can be
> - * either connected to it directly, or through an intermediate bridge:
> + * either connected to it directly, or through an intermediate bridge::
>   *
>   *     encoder ---> bridge B ---> bridge A
>   *
> diff --git a/drivers/gpu/drm/drm_fb_cma_helper.c b/drivers/gpu/drm/drm_fb_cma_helper.c
> index 2b33b191a172..c50a0ba6fdba 100644
> --- a/drivers/gpu/drm/drm_fb_cma_helper.c
> +++ b/drivers/gpu/drm/drm_fb_cma_helper.c
> @@ -52,7 +52,7 @@ struct drm_fbdev_cma {
>   * will be set up automatically. dirty() is called by
>   * drm_fb_helper_deferred_io() in process context (struct delayed_work).
>   *
> - * Example fbdev deferred io code:
> + * Example fbdev deferred io code::
>   *
>   *     static int driver_fbdev_fb_dirty(struct drm_framebuffer *fb,
>   *                                      struct drm_file *file_priv,
> diff --git a/drivers/gpu/drm/drm_fops.c b/drivers/gpu/drm/drm_fops.c
> index 5921b203503a..323c238fcac7 100644
> --- a/drivers/gpu/drm/drm_fops.c
> +++ b/drivers/gpu/drm/drm_fops.c
> @@ -68,7 +68,7 @@ DEFINE_MUTEX(drm_global_mutex);
>   * specific implementations. For GEM-based drivers this is drm_gem_mmap().
>   *
>   * No other file operations are supported by the DRM userspace API. Overall the
> - * following is an example #file_operations structure:
> + * following is an example #file_operations structure::
>   *
>   *     static const example_drm_fops = {
>   *             .owner = THIS_MODULE,
> diff --git a/drivers/gpu/drm/drm_modes.c b/drivers/gpu/drm/drm_modes.c
> index e5e6f504d8cc..aae86c1857ec 100644
> --- a/drivers/gpu/drm/drm_modes.c
> +++ b/drivers/gpu/drm/drm_modes.c
> @@ -552,7 +552,10 @@ EXPORT_SYMBOL(drm_gtf_mode_complex);
>   * I also refer to the function of fb_get_mode in the file of
>   * drivers/video/fbmon.c
>   *
> - * Standard GTF parameters:
> + * Standard GTF parameters
> + *
> + * ::
> + *
>   *     M = 600
>   *     C = 40
>   *     K = 128
> diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c
> index f33ebe638a28..61146f5b4f56 100644
> --- a/drivers/gpu/drm/drm_modeset_lock.c
> +++ b/drivers/gpu/drm/drm_modeset_lock.c
> @@ -37,7 +37,7 @@
>   *
>   * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt
>   *
> - * The basic usage pattern is to:
> + * The basic usage pattern is to::
>   *
>   *     drm_modeset_acquire_init(&ctx)
>   *     retry:
> diff --git a/drivers/gpu/drm/drm_vma_manager.c b/drivers/gpu/drm/drm_vma_manager.c
> index 2f2ecde8285b..f306c8855978 100644
> --- a/drivers/gpu/drm/drm_vma_manager.c
> +++ b/drivers/gpu/drm/drm_vma_manager.c
> @@ -127,6 +127,9 @@ EXPORT_SYMBOL(drm_vma_offset_manager_destroy);
>   * used to implement weakly referenced lookups using kref_get_unless_zero().
>   *
>   * Example:
> + *
> + * ::
> + *
>   *     drm_vma_offset_lock_lookup(mgr);
>   *     node = drm_vma_offset_lookup_locked(mgr);
>   *     if (node)
> diff --git a/drivers/gpu/drm/i915/i915_reg.h b/drivers/gpu/drm/i915/i915_reg.h
> index 216cc4ba74ee..d25dd1d694bc 100644
> --- a/drivers/gpu/drm/i915/i915_reg.h
> +++ b/drivers/gpu/drm/i915/i915_reg.h
> @@ -886,7 +886,7 @@ enum skl_disp_power_wells {
>   * PLLs can be routed to any transcoder A/B/C.
>   *
>   * Note: DDI0 is digital port B, DD1 is digital port C, and DDI2 is
> - * digital port D (CHV) or port A (BXT).
> + * digital port D (CHV) or port A (BXT). ::
>   *
>   *
>   *     Dual channel PHY (VLV/CHV/BXT)
> diff --git a/drivers/gpu/drm/i915/i915_vgpu.c b/drivers/gpu/drm/i915/i915_vgpu.c
> index d5a7a5e7ee7e..004326291854 100644
> --- a/drivers/gpu/drm/i915/i915_vgpu.c
> +++ b/drivers/gpu/drm/i915/i915_vgpu.c
> @@ -150,28 +150,28 @@ static int vgt_balloon_space(struct drm_mm *mm,
>   * of its graphic space being zero. Yet there are some portions ballooned out(
>   * the shadow part, which are marked as reserved by drm allocator). From the
>   * host point of view, the graphic address space is partitioned by multiple
> - * vGPUs in different VMs.
> + * vGPUs in different VMs. ::
>   *
>   *                        vGPU1 view         Host view
>   *             0 ------> +-----------+     +-----------+
> - *               ^       |///////////|     |   vGPU3   |
> - *               |       |///////////|     +-----------+
> - *               |       |///////////|     |   vGPU2   |
> + *               ^       |###########|     |   vGPU3   |
> + *               |       |###########|     +-----------+
> + *               |       |###########|     |   vGPU2   |
>   *               |       +-----------+     +-----------+
>   *        mappable GM    | available | ==> |   vGPU1   |
>   *               |       +-----------+     +-----------+
> - *               |       |///////////|     |           |
> - *               v       |///////////|     |   Host    |
> + *               |       |###########|     |           |
> + *               v       |###########|     |   Host    |
>   *               +=======+===========+     +===========+
> - *               ^       |///////////|     |   vGPU3   |
> - *               |       |///////////|     +-----------+
> - *               |       |///////////|     |   vGPU2   |
> + *               ^       |###########|     |   vGPU3   |
> + *               |       |###########|     +-----------+
> + *               |       |###########|     |   vGPU2   |
>   *               |       +-----------+     +-----------+
>   *      unmappable GM    | available | ==> |   vGPU1   |
>   *               |       +-----------+     +-----------+
> - *               |       |///////////|     |           |
> - *               |       |///////////|     |   Host    |
> - *               v       |///////////|     |           |
> + *               |       |###########|     |           |
> + *               |       |###########|     |   Host    |
> + *               v       |###########|     |           |
>   * total GM size ------> +-----------+     +-----------+
>   *
>   * Returns:
> diff --git a/include/drm/drm_modes.h b/include/drm/drm_modes.h
> index 625966a906f2..ff481770d76b 100644
> --- a/include/drm/drm_modes.h
> +++ b/include/drm/drm_modes.h
> @@ -169,6 +169,8 @@ enum drm_mode_status {
>   *
>   * The horizontal and vertical timings are defined per the following diagram.
>   *
> + * ::
> + *
>   *
>   *               Active                 Front           Sync           Back
>   *              Region                 Porch                          Porch

-- 
Jani Nikula, Intel Open Source Technology Center


More information about the dri-devel mailing list