[PATCH 1/2] doc/sphinx: Enable keep_warnings

[PATCH 1/2] doc/sphinx: Enable keep_warnings

[Daniel Vetter]

Unfortunately warnings generated after parsing in sphinx can end up
with entirely bogus files and line numbers as sources. Strangely for
outright errors this is not a problem. Trying to convert warnings to
errors also doesn't fix it.

The only way to get useful output out of sphinx to be able to root
cause the error seems to be enabling keep_warnings, which inserts
a System Message into the actual output. Not pretty at all, but I
don't really want to fix up core rst/sphinx code, and this gets the job
done meanwhile.

Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 Documentation/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6cc41a0555a3..a131139675cc 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -125,7 +125,7 @@ pygments_style = 'sphinx'
 #modindex_common_prefix = []
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
+keep_warnings = True
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
-- 
2.8.1

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[PATCH 2/2] drm/doc: Fix more kerneldoc/sphinx warnings

[Daniel Vetter]

These are the leftovers I could only track down using keep_warnings =
True. For some of them we might want to update our style guide on how
to reference structures and constants, not sure ...

Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 drivers/gpu/drm/drm_crtc.c              |  4 ++--
 drivers/gpu/drm/drm_fb_helper.c         |  2 +-
 drivers/gpu/drm/drm_irq.c               |  8 +++----
 drivers/gpu/drm/drm_simple_kms_helper.c |  2 +-
 drivers/gpu/drm/i915/i915_vgpu.c        | 42 ++++++++++++++++-----------------
 drivers/gpu/drm/i915/intel_audio.c      |  6 ++---
 drivers/gpu/drm/i915/intel_guc_fwif.h   |  5 ++--
 include/drm/drm_crtc.h                  |  8 +++----
 include/drm/drm_gem.h                   |  4 ++--
 9 files changed, 41 insertions(+), 40 deletions(-)

diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
index f9f2506b1855..420f4fc8e6a7 100644
--- a/drivers/gpu/drm/drm_crtc.c
+++ b/drivers/gpu/drm/drm_crtc.c
@@ -1273,7 +1273,7 @@ static unsigned int drm_num_planes(struct drm_device *dev)
  * @plane: plane object to init
  * @possible_crtcs: bitmask of possible CRTCs
  * @funcs: callbacks for the new plane
- * @formats: array of supported formats (%DRM_FORMAT_*)
+ * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
  * @type: type of plane (overlay, primary, cursor)
  * @name: printf style format string for the plane name, or NULL for default name
@@ -1388,7 +1388,7 @@ static void drm_plane_unregister_all(struct drm_device *dev)
  * @plane: plane object to init
  * @possible_crtcs: bitmask of possible CRTCs
  * @funcs: callbacks for the new plane
- * @formats: array of supported formats (%DRM_FORMAT_*)
+ * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
  * @is_primary: plane type (primary vs overlay)
  *
diff --git a/drivers/gpu/drm/drm_fb_helper.c b/drivers/gpu/drm/drm_fb_helper.c
index ce54e985d91b..95f405e04f5f 100644
--- a/drivers/gpu/drm/drm_fb_helper.c
+++ b/drivers/gpu/drm/drm_fb_helper.c
@@ -2194,7 +2194,7 @@ EXPORT_SYMBOL(drm_fb_helper_initial_config);
  * @fb_helper: the drm_fb_helper
  *
  * Scan the connectors attached to the fb_helper and try to put together a
- * setup after *notification of a change in output configuration.
+ * setup after notification of a change in output configuration.
  *
  * Called at runtime, takes the mode config locks to be able to check/change the
  * modeset configuration. Must be run from process context (which usually means
diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c
index b49a4a6e97cd..a33465d8e133 100644
--- a/drivers/gpu/drm/drm_irq.c
+++ b/drivers/gpu/drm/drm_irq.c
@@ -713,10 +713,10 @@ EXPORT_SYMBOL(drm_calc_timestamping_constants);
  * Negative value on error, failure or if not supported in current
  * video mode:
  *
- * -EINVAL   - Invalid CRTC.
- * -EAGAIN   - Temporary unavailable, e.g., called before initial modeset.
- * -ENOTSUPP - Function not supported in current display mode.
- * -EIO      - Failed, e.g., due to failed scanout position query.
+ * -EINVAL    Invalid CRTC.
+ * -EAGAIN    Temporary unavailable, e.g., called before initial modeset.
+ * -ENOTSUPP  Function not supported in current display mode.
+ * -EIO       Failed, e.g., due to failed scanout position query.
  *
  * Returns or'ed positive status flags on success:
  *
diff --git a/drivers/gpu/drm/drm_simple_kms_helper.c b/drivers/gpu/drm/drm_simple_kms_helper.c
index 0db36d27e90b..4e1de31f072b 100644
--- a/drivers/gpu/drm/drm_simple_kms_helper.c
+++ b/drivers/gpu/drm/drm_simple_kms_helper.c
@@ -152,7 +152,7 @@ static const struct drm_plane_funcs drm_simple_kms_plane_funcs = {
  * @dev: DRM device
  * @pipe: simple display pipe object to initialize
  * @funcs: callbacks for the display pipe (optional)
- * @formats: array of supported formats (%DRM_FORMAT_*)
+ * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
  * @connector: connector to attach and register
  *
diff --git a/drivers/gpu/drm/i915/i915_vgpu.c b/drivers/gpu/drm/i915/i915_vgpu.c
index 142bac976919..ca2e91259948 100644
--- a/drivers/gpu/drm/i915/i915_vgpu.c
+++ b/drivers/gpu/drm/i915/i915_vgpu.c
@@ -156,27 +156,27 @@ static int vgt_balloon_space(struct drm_mm *mm,
  * host point of view, the graphic address space is partitioned by multiple
  * vGPUs in different VMs. ::
  *
- *                        vGPU1 view         Host view
- *             0 ------> +-----------+     +-----------+
- *               ^       |###########|     |   vGPU3   |
- *               |       |###########|     +-----------+
- *               |       |###########|     |   vGPU2   |
- *               |       +-----------+     +-----------+
- *        mappable GM    | available | ==> |   vGPU1   |
- *               |       +-----------+     +-----------+
- *               |       |###########|     |           |
- *               v       |###########|     |   Host    |
- *               +=======+===========+     +===========+
- *               ^       |###########|     |   vGPU3   |
- *               |       |###########|     +-----------+
- *               |       |###########|     |   vGPU2   |
- *               |       +-----------+     +-----------+
- *      unmappable GM    | available | ==> |   vGPU1   |
- *               |       +-----------+     +-----------+
- *               |       |###########|     |           |
- *               |       |###########|     |   Host    |
- *               v       |###########|     |           |
- * total GM size ------> +-----------+     +-----------+
+ *                         vGPU1 view         Host view
+ *              0 ------> +-----------+     +-----------+
+ *                ^       |###########|     |   vGPU3   |
+ *                |       |###########|     +-----------+
+ *                |       |###########|     |   vGPU2   |
+ *                |       +-----------+     +-----------+
+ *         mappable GM    | available | ==> |   vGPU1   |
+ *                |       +-----------+     +-----------+
+ *                |       |###########|     |           |
+ *                v       |###########|     |   Host    |
+ *                +=======+===========+     +===========+
+ *                ^       |###########|     |   vGPU3   |
+ *                |       |###########|     +-----------+
+ *                |       |###########|     |   vGPU2   |
+ *                |       +-----------+     +-----------+
+ *       unmappable GM    | available | ==> |   vGPU1   |
+ *                |       +-----------+     +-----------+
+ *                |       |###########|     |           |
+ *                |       |###########|     |   Host    |
+ *                v       |###########|     |           |
+ *  total GM size ------> +-----------+     +-----------+
  *
  * Returns:
  * zero on success, non-zero if configuration invalid or ballooning failed
diff --git a/drivers/gpu/drm/i915/intel_audio.c b/drivers/gpu/drm/i915/intel_audio.c
index 6700a7be7f78..500b38dd8721 100644
--- a/drivers/gpu/drm/i915/intel_audio.c
+++ b/drivers/gpu/drm/i915/intel_audio.c
@@ -51,10 +51,10 @@
  * related registers. (The notable exception is the power management, not
  * covered here.)
  *
- * The struct i915_audio_component is used to interact between the graphics
- * and audio drivers. The struct i915_audio_component_ops *ops in it is
+ * The struct &i915_audio_component is used to interact between the graphics
+ * and audio drivers. The struct &i915_audio_component_ops @ops in it is
  * defined in graphics driver and called in audio driver. The
- * struct i915_audio_component_audio_ops *audio_ops is called from i915 driver.
+ * struct &i915_audio_component_audio_ops @audio_ops is called from i915 driver.
  */
 
 static const struct {
diff --git a/drivers/gpu/drm/i915/intel_guc_fwif.h b/drivers/gpu/drm/i915/intel_guc_fwif.h
index 944786d7075b..e40db2d2ae99 100644
--- a/drivers/gpu/drm/i915/intel_guc_fwif.h
+++ b/drivers/gpu/drm/i915/intel_guc_fwif.h
@@ -155,6 +155,7 @@
  *
  *     +-------------------------------+
  *     |        guc_css_header         |
+ *     |                               |
  *     | contains major/minor version  |
  *     +-------------------------------+
  *     |             uCode             |
@@ -176,10 +177,10 @@
  *
  * 1. Header, uCode and RSA are must-have components.
  * 2. All firmware components, if they present, are in the sequence illustrated
- * in the layout table above.
+ *    in the layout table above.
  * 3. Length info of each component can be found in header, in dwords.
  * 4. Modulus and exponent key are not required by driver. They may not appear
- * in fw. So driver will load a truncated firmware in this case.
+ *    in fw. So driver will load a truncated firmware in this case.
  */
 
 struct guc_css_header {
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index 4aa4c4341d01..65e1a0852200 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -1193,7 +1193,7 @@ struct drm_encoder_funcs {
  * @head: list management
  * @base: base KMS object
  * @name: human readable name, can be overwritten by the driver
- * @encoder_type: one of the %DRM_MODE_ENCODER_<foo> types in drm_mode.h
+ * @encoder_type: one of the DRM_MODE_ENCODER_<foo> types in drm_mode.h
  * @possible_crtcs: bitmask of potential CRTC bindings
  * @possible_clones: bitmask of potential sibling encoders for cloning
  * @crtc: currently bound CRTC
@@ -1246,7 +1246,7 @@ struct drm_encoder {
  * @head: list management
  * @base: base KMS object
  * @name: human readable name, can be overwritten by the driver
- * @connector_type: one of the %DRM_MODE_CONNECTOR_<foo> types from drm_mode.h
+ * @connector_type: one of the DRM_MODE_CONNECTOR_<foo> types from drm_mode.h
  * @connector_type_id: index into connector type enum
  * @interlace_allowed: can this connector handle interlaced modes?
  * @doublescan_allowed: can this connector handle doublescan?
@@ -1259,11 +1259,11 @@ struct drm_encoder {
  * @funcs: connector control functions
  * @edid_blob_ptr: DRM property containing EDID if present
  * @properties: property tracking for this connector
- * @polled: a %DRM_CONNECTOR_POLL_<foo> value for core driven polling
+ * @polled: a DRM_CONNECTOR_POLL_<foo> value for core driven polling
  * @dpms: current dpms state
  * @helper_private: mid-layer private data
  * @cmdline_mode: mode line parsed from the kernel cmdline for this connector
- * @force: a %DRM_FORCE_<foo> state for forced mode sets
+ * @force: a DRM_FORCE_<foo> state for forced mode sets
  * @override_edid: has the EDID been overwritten through debugfs for testing?
  * @encoder_ids: valid encoders for this connector
  * @encoder: encoder driving this connector, if any
diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h
index fca1cd1b9c26..9f63736e6163 100644
--- a/include/drm/drm_gem.h
+++ b/include/drm/drm_gem.h
@@ -210,8 +210,8 @@ drm_gem_object_reference(struct drm_gem_object *obj)
  * drm_gem_object_unreference_unlocked().
  *
  * Drivers should never call this directly in their code. Instead they should
- * wrap it up into a driver_gem_object_unreference(struct driver_gem_object
- * *obj) wrapper function, and use that. Shared code should never call this, to
+ * wrap it up into a ``driver_gem_object_unreference(struct driver_gem_object
+ * *obj)`` wrapper function, and use that. Shared code should never call this, to
  * avoid breaking drivers by accident which still depend upon dev->struct_mutex
  * locking.
  */
-- 
2.8.1

Re: [PATCH 2/2] drm/doc: Fix more kerneldoc/sphinx warnings

[Daniel Vetter]

On Tue, Jul 19, 2016 at 01:42:55PM +0200, Daniel Vetter wrote:
> These are the leftovers I could only track down using keep_warnings =
> True. For some of them we might want to update our style guide on how
> to reference structures and constants, not sure ...
> 
> Cc: Markus Heiser <markus.heiser@darmarit.de>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>

Aside: With this and the latest docs-next branch from Jon it's possible to
compile test doc changes (e.g. with git rebase -x) using:

$ make IGNORE_DOCBOOKS=1 SPHINXOPTS=-W htmldocs

To make this easier I've quickly pulled in the latest docs-next into
drm-intel-nightly.

Cheers, Daniel

> ---
>  drivers/gpu/drm/drm_crtc.c              |  4 ++--
>  drivers/gpu/drm/drm_fb_helper.c         |  2 +-
>  drivers/gpu/drm/drm_irq.c               |  8 +++----
>  drivers/gpu/drm/drm_simple_kms_helper.c |  2 +-
>  drivers/gpu/drm/i915/i915_vgpu.c        | 42 ++++++++++++++++-----------------
>  drivers/gpu/drm/i915/intel_audio.c      |  6 ++---
>  drivers/gpu/drm/i915/intel_guc_fwif.h   |  5 ++--
>  include/drm/drm_crtc.h                  |  8 +++----
>  include/drm/drm_gem.h                   |  4 ++--
>  9 files changed, 41 insertions(+), 40 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
> index f9f2506b1855..420f4fc8e6a7 100644
> --- a/drivers/gpu/drm/drm_crtc.c
> +++ b/drivers/gpu/drm/drm_crtc.c
> @@ -1273,7 +1273,7 @@ static unsigned int drm_num_planes(struct drm_device *dev)
>   * @plane: plane object to init
>   * @possible_crtcs: bitmask of possible CRTCs
>   * @funcs: callbacks for the new plane
> - * @formats: array of supported formats (%DRM_FORMAT_*)
> + * @formats: array of supported formats (DRM_FORMAT\_\*)
>   * @format_count: number of elements in @formats
>   * @type: type of plane (overlay, primary, cursor)
>   * @name: printf style format string for the plane name, or NULL for default name
> @@ -1388,7 +1388,7 @@ static void drm_plane_unregister_all(struct drm_device *dev)
>   * @plane: plane object to init
>   * @possible_crtcs: bitmask of possible CRTCs
>   * @funcs: callbacks for the new plane
> - * @formats: array of supported formats (%DRM_FORMAT_*)
> + * @formats: array of supported formats (DRM_FORMAT\_\*)
>   * @format_count: number of elements in @formats
>   * @is_primary: plane type (primary vs overlay)
>   *
> diff --git a/drivers/gpu/drm/drm_fb_helper.c b/drivers/gpu/drm/drm_fb_helper.c
> index ce54e985d91b..95f405e04f5f 100644
> --- a/drivers/gpu/drm/drm_fb_helper.c
> +++ b/drivers/gpu/drm/drm_fb_helper.c
> @@ -2194,7 +2194,7 @@ EXPORT_SYMBOL(drm_fb_helper_initial_config);
>   * @fb_helper: the drm_fb_helper
>   *
>   * Scan the connectors attached to the fb_helper and try to put together a
> - * setup after *notification of a change in output configuration.
> + * setup after notification of a change in output configuration.
>   *
>   * Called at runtime, takes the mode config locks to be able to check/change the
>   * modeset configuration. Must be run from process context (which usually means
> diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c
> index b49a4a6e97cd..a33465d8e133 100644
> --- a/drivers/gpu/drm/drm_irq.c
> +++ b/drivers/gpu/drm/drm_irq.c
> @@ -713,10 +713,10 @@ EXPORT_SYMBOL(drm_calc_timestamping_constants);
>   * Negative value on error, failure or if not supported in current
>   * video mode:
>   *
> - * -EINVAL   - Invalid CRTC.
> - * -EAGAIN   - Temporary unavailable, e.g., called before initial modeset.
> - * -ENOTSUPP - Function not supported in current display mode.
> - * -EIO      - Failed, e.g., due to failed scanout position query.
> + * -EINVAL    Invalid CRTC.
> + * -EAGAIN    Temporary unavailable, e.g., called before initial modeset.
> + * -ENOTSUPP  Function not supported in current display mode.
> + * -EIO       Failed, e.g., due to failed scanout position query.
>   *
>   * Returns or'ed positive status flags on success:
>   *
> diff --git a/drivers/gpu/drm/drm_simple_kms_helper.c b/drivers/gpu/drm/drm_simple_kms_helper.c
> index 0db36d27e90b..4e1de31f072b 100644
> --- a/drivers/gpu/drm/drm_simple_kms_helper.c
> +++ b/drivers/gpu/drm/drm_simple_kms_helper.c
> @@ -152,7 +152,7 @@ static const struct drm_plane_funcs drm_simple_kms_plane_funcs = {
>   * @dev: DRM device
>   * @pipe: simple display pipe object to initialize
>   * @funcs: callbacks for the display pipe (optional)
> - * @formats: array of supported formats (%DRM_FORMAT_*)
> + * @formats: array of supported formats (DRM_FORMAT\_\*)
>   * @format_count: number of elements in @formats
>   * @connector: connector to attach and register
>   *
> diff --git a/drivers/gpu/drm/i915/i915_vgpu.c b/drivers/gpu/drm/i915/i915_vgpu.c
> index 142bac976919..ca2e91259948 100644
> --- a/drivers/gpu/drm/i915/i915_vgpu.c
> +++ b/drivers/gpu/drm/i915/i915_vgpu.c
> @@ -156,27 +156,27 @@ static int vgt_balloon_space(struct drm_mm *mm,
>   * host point of view, the graphic address space is partitioned by multiple
>   * vGPUs in different VMs. ::
>   *
> - *                        vGPU1 view         Host view
> - *             0 ------> +-----------+     +-----------+
> - *               ^       |###########|     |   vGPU3   |
> - *               |       |###########|     +-----------+
> - *               |       |###########|     |   vGPU2   |
> - *               |       +-----------+     +-----------+
> - *        mappable GM    | available | ==> |   vGPU1   |
> - *               |       +-----------+     +-----------+
> - *               |       |###########|     |           |
> - *               v       |###########|     |   Host    |
> - *               +=======+===========+     +===========+
> - *               ^       |###########|     |   vGPU3   |
> - *               |       |###########|     +-----------+
> - *               |       |###########|     |   vGPU2   |
> - *               |       +-----------+     +-----------+
> - *      unmappable GM    | available | ==> |   vGPU1   |
> - *               |       +-----------+     +-----------+
> - *               |       |###########|     |           |
> - *               |       |###########|     |   Host    |
> - *               v       |###########|     |           |
> - * total GM size ------> +-----------+     +-----------+
> + *                         vGPU1 view         Host view
> + *              0 ------> +-----------+     +-----------+
> + *                ^       |###########|     |   vGPU3   |
> + *                |       |###########|     +-----------+
> + *                |       |###########|     |   vGPU2   |
> + *                |       +-----------+     +-----------+
> + *         mappable GM    | available | ==> |   vGPU1   |
> + *                |       +-----------+     +-----------+
> + *                |       |###########|     |           |
> + *                v       |###########|     |   Host    |
> + *                +=======+===========+     +===========+
> + *                ^       |###########|     |   vGPU3   |
> + *                |       |###########|     +-----------+
> + *                |       |###########|     |   vGPU2   |
> + *                |       +-----------+     +-----------+
> + *       unmappable GM    | available | ==> |   vGPU1   |
> + *                |       +-----------+     +-----------+
> + *                |       |###########|     |           |
> + *                |       |###########|     |   Host    |
> + *                v       |###########|     |           |
> + *  total GM size ------> +-----------+     +-----------+
>   *
>   * Returns:
>   * zero on success, non-zero if configuration invalid or ballooning failed
> diff --git a/drivers/gpu/drm/i915/intel_audio.c b/drivers/gpu/drm/i915/intel_audio.c
> index 6700a7be7f78..500b38dd8721 100644
> --- a/drivers/gpu/drm/i915/intel_audio.c
> +++ b/drivers/gpu/drm/i915/intel_audio.c
> @@ -51,10 +51,10 @@
>   * related registers. (The notable exception is the power management, not
>   * covered here.)
>   *
> - * The struct i915_audio_component is used to interact between the graphics
> - * and audio drivers. The struct i915_audio_component_ops *ops in it is
> + * The struct &i915_audio_component is used to interact between the graphics
> + * and audio drivers. The struct &i915_audio_component_ops @ops in it is
>   * defined in graphics driver and called in audio driver. The
> - * struct i915_audio_component_audio_ops *audio_ops is called from i915 driver.
> + * struct &i915_audio_component_audio_ops @audio_ops is called from i915 driver.
>   */
>  
>  static const struct {
> diff --git a/drivers/gpu/drm/i915/intel_guc_fwif.h b/drivers/gpu/drm/i915/intel_guc_fwif.h
> index 944786d7075b..e40db2d2ae99 100644
> --- a/drivers/gpu/drm/i915/intel_guc_fwif.h
> +++ b/drivers/gpu/drm/i915/intel_guc_fwif.h
> @@ -155,6 +155,7 @@
>   *
>   *     +-------------------------------+
>   *     |        guc_css_header         |
> + *     |                               |
>   *     | contains major/minor version  |
>   *     +-------------------------------+
>   *     |             uCode             |
> @@ -176,10 +177,10 @@
>   *
>   * 1. Header, uCode and RSA are must-have components.
>   * 2. All firmware components, if they present, are in the sequence illustrated
> - * in the layout table above.
> + *    in the layout table above.
>   * 3. Length info of each component can be found in header, in dwords.
>   * 4. Modulus and exponent key are not required by driver. They may not appear
> - * in fw. So driver will load a truncated firmware in this case.
> + *    in fw. So driver will load a truncated firmware in this case.
>   */
>  
>  struct guc_css_header {
> diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
> index 4aa4c4341d01..65e1a0852200 100644
> --- a/include/drm/drm_crtc.h
> +++ b/include/drm/drm_crtc.h
> @@ -1193,7 +1193,7 @@ struct drm_encoder_funcs {
>   * @head: list management
>   * @base: base KMS object
>   * @name: human readable name, can be overwritten by the driver
> - * @encoder_type: one of the %DRM_MODE_ENCODER_<foo> types in drm_mode.h
> + * @encoder_type: one of the DRM_MODE_ENCODER_<foo> types in drm_mode.h
>   * @possible_crtcs: bitmask of potential CRTC bindings
>   * @possible_clones: bitmask of potential sibling encoders for cloning
>   * @crtc: currently bound CRTC
> @@ -1246,7 +1246,7 @@ struct drm_encoder {
>   * @head: list management
>   * @base: base KMS object
>   * @name: human readable name, can be overwritten by the driver
> - * @connector_type: one of the %DRM_MODE_CONNECTOR_<foo> types from drm_mode.h
> + * @connector_type: one of the DRM_MODE_CONNECTOR_<foo> types from drm_mode.h
>   * @connector_type_id: index into connector type enum
>   * @interlace_allowed: can this connector handle interlaced modes?
>   * @doublescan_allowed: can this connector handle doublescan?
> @@ -1259,11 +1259,11 @@ struct drm_encoder {
>   * @funcs: connector control functions
>   * @edid_blob_ptr: DRM property containing EDID if present
>   * @properties: property tracking for this connector
> - * @polled: a %DRM_CONNECTOR_POLL_<foo> value for core driven polling
> + * @polled: a DRM_CONNECTOR_POLL_<foo> value for core driven polling
>   * @dpms: current dpms state
>   * @helper_private: mid-layer private data
>   * @cmdline_mode: mode line parsed from the kernel cmdline for this connector
> - * @force: a %DRM_FORCE_<foo> state for forced mode sets
> + * @force: a DRM_FORCE_<foo> state for forced mode sets
>   * @override_edid: has the EDID been overwritten through debugfs for testing?
>   * @encoder_ids: valid encoders for this connector
>   * @encoder: encoder driving this connector, if any
> diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h
> index fca1cd1b9c26..9f63736e6163 100644
> --- a/include/drm/drm_gem.h
> +++ b/include/drm/drm_gem.h
> @@ -210,8 +210,8 @@ drm_gem_object_reference(struct drm_gem_object *obj)
>   * drm_gem_object_unreference_unlocked().
>   *
>   * Drivers should never call this directly in their code. Instead they should
> - * wrap it up into a driver_gem_object_unreference(struct driver_gem_object
> - * *obj) wrapper function, and use that. Shared code should never call this, to
> + * wrap it up into a ``driver_gem_object_unreference(struct driver_gem_object
> + * *obj)`` wrapper function, and use that. Shared code should never call this, to
>   * avoid breaking drivers by accident which still depend upon dev->struct_mutex
>   * locking.
>   */
> -- 
> 2.8.1
> 

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

Re: [PATCH 2/2] drm/doc: Fix more kerneldoc/sphinx warnings

[Mauro Carvalho Chehab]

Em Tue, 19 Jul 2016 14:36:50 +0200
Daniel Vetter <daniel@ffwll.ch> escreveu:

> On Tue, Jul 19, 2016 at 01:42:55PM +0200, Daniel Vetter wrote:
> > These are the leftovers I could only track down using keep_warnings =
> > True. For some of them we might want to update our style guide on how
> > to reference structures and constants, not sure ...
> > 
> > Cc: Markus Heiser <markus.heiser@darmarit.de>
> > Cc: Jonathan Corbet <corbet@lwn.net>
> > Cc: linux-doc@vger.kernel.org
> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>  
> 
> Aside: With this and the latest docs-next branch from Jon it's possible to
> compile test doc changes (e.g. with git rebase -x) using:
> 
> $ make IGNORE_DOCBOOKS=1 SPHINXOPTS=-W htmldocs

Unfortunately, we'll not get rid of Sphinx warnings any time soon.

The Sphinx function parser is really broken, even on version 1.4.5.

Every time Sphinx finds a typedef argument or return value, like here:

	ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len);

It produces a very ugly noisy warning:

./drivers/media/dvb-core/dvb_ringbuffer.h:149: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters and qualifiers
  Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
    ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
    --------^
If the function has a return type:
  Error in declarator or parameters and qualifiers
  If pointer to member declarator:
    Invalid definition: Expected '::' in pointer to member (function). [error at 37]
      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
      -------------------------------------^
  If declarator-id:
    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
      ------------------------------------------------------------------------------------------------------^

I guess that the problem is because Sphinx tries to generate a CPP like
function name for cross-ref, and such parser is unable to handle typedef
arguments. IMHO, this is broken by design.


Thanks,
Mauro

Re: [PATCH 2/2] drm/doc: Fix more kerneldoc/sphinx warnings

[Markus Heiser]

Am 20.07.2016 um 14:20 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:

> Em Tue, 19 Jul 2016 14:36:50 +0200
> Daniel Vetter <daniel@ffwll.ch> escreveu:
> 
>> On Tue, Jul 19, 2016 at 01:42:55PM +0200, Daniel Vetter wrote:
>>> These are the leftovers I could only track down using keep_warnings =
>>> True. For some of them we might want to update our style guide on how
>>> to reference structures and constants, not sure ...
>>> 
>>> Cc: Markus Heiser <markus.heiser@darmarit.de>
>>> Cc: Jonathan Corbet <corbet@lwn.net>
>>> Cc: linux-doc@vger.kernel.org
>>> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>  
>> 
>> Aside: With this and the latest docs-next branch from Jon it's possible to
>> compile test doc changes (e.g. with git rebase -x) using:
>> 
>> $ make IGNORE_DOCBOOKS=1 SPHINXOPTS=-W htmldocs
> 
> Unfortunately, we'll not get rid of Sphinx warnings any time soon.
> 
> The Sphinx function parser is really broken, even on version 1.4.5.
> 
> Every time Sphinx finds a typedef argument or return value, like here:
> 
> 	ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len);
> 
> It produces a very ugly noisy warning:
> 
> ./drivers/media/dvb-core/dvb_ringbuffer.h:149: WARNING: Error when parsing function declaration.
> If the function has no return type:
>  Error in declarator or parameters and qualifiers
>  Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
>    ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
>    --------^
> If the function has a return type:
>  Error in declarator or parameters and qualifiers
>  If pointer to member declarator:
>    Invalid definition: Expected '::' in pointer to member (function). [error at 37]
>      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
>      -------------------------------------^
>  If declarator-id:
>    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
>      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
>      ------------------------------------------------------------------------------------------------------^
> 

Aaargh ... it seems you are right. 

There is a discussion about function overloading and identifiers

  https://github.com/sphinx-doc/sphinx/issues/2682#issuecomment-229515888

If we use the C-domain ("..c:function::"  instead of ".. cpp:function::")
this error did not expire. But using the C-domain has other drawbacks, we
discussed with ioctl.

May be it is better to switch to the c-domain and try to handle 
these drawbacks ... I don't know.

> I guess that the problem is because Sphinx tries to generate a CPP like
> function name for cross-ref, and such parser is unable to handle typedef
> arguments. IMHO, this is broken by design.

by design? 

-- Markus --

> 
> 
> Thanks,
> Mauro

Re: [PATCH 2/2] drm/doc: Fix more kerneldoc/sphinx warnings

[Mauro Carvalho Chehab]

Em Wed, 20 Jul 2016 20:35:09 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 20.07.2016 um 14:20 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > Em Tue, 19 Jul 2016 14:36:50 +0200
> > Daniel Vetter <daniel@ffwll.ch> escreveu:
> >   
> >> On Tue, Jul 19, 2016 at 01:42:55PM +0200, Daniel Vetter wrote:  
> >>> These are the leftovers I could only track down using keep_warnings =
> >>> True. For some of them we might want to update our style guide on how
> >>> to reference structures and constants, not sure ...
> >>> 
> >>> Cc: Markus Heiser <markus.heiser@darmarit.de>
> >>> Cc: Jonathan Corbet <corbet@lwn.net>
> >>> Cc: linux-doc@vger.kernel.org
> >>> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>    
> >> 
> >> Aside: With this and the latest docs-next branch from Jon it's possible to
> >> compile test doc changes (e.g. with git rebase -x) using:
> >> 
> >> $ make IGNORE_DOCBOOKS=1 SPHINXOPTS=-W htmldocs  
> > 
> > Unfortunately, we'll not get rid of Sphinx warnings any time soon.
> > 
> > The Sphinx function parser is really broken, even on version 1.4.5.
> > 
> > Every time Sphinx finds a typedef argument or return value, like here:
> > 
> > 	ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len);
> > 
> > It produces a very ugly noisy warning:
> > 
> > ./drivers/media/dvb-core/dvb_ringbuffer.h:149: WARNING: Error when parsing function declaration.
> > If the function has no return type:
> >  Error in declarator or parameters and qualifiers
> >  Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
> >    ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> >    --------^
> > If the function has a return type:
> >  Error in declarator or parameters and qualifiers
> >  If pointer to member declarator:
> >    Invalid definition: Expected '::' in pointer to member (function). [error at 37]
> >      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> >      -------------------------------------^
> >  If declarator-id:
> >    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
> >      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> >      ------------------------------------------------------------------------------------------------------^
> >   
> 
> Aaargh ... it seems you are right. 
> 
> There is a discussion about function overloading and identifiers
> 
>   https://github.com/sphinx-doc/sphinx/issues/2682#issuecomment-229515888
> 
> If we use the C-domain ("..c:function::"  instead of ".. cpp:function::")
> this error did not expire. But using the C-domain has other drawbacks, we
> discussed with ioctl.
> 
> May be it is better to switch to the c-domain and try to handle 
> these drawbacks ... I don't know.
> 
> > I guess that the problem is because Sphinx tries to generate a CPP like
> > function name for cross-ref, and such parser is unable to handle typedef
> > arguments. IMHO, this is broken by design.  
> 
> by design? 

What I mean is that, in order to solve typedefs, Sphinx would need to 
parse all include files that contains typedefs, in order to discover if
a typedef argument is used, and parse such argument to the original one,
e. g., if we have something like:

	typedef long int size_t;

it would need to replace "size_t" by "long int" internally, before being
able to produce an unique reference for a function that uses "size_t"
as an argument or returned value. However, AFAICT, Sphinx is not like
Doxygen: it doesn't parse header files. So, there's no easy fix.

On the other hand, the C domain is too simple: it assumes that
all functions, enums, etc are global, e. g. there should be just one
function called "ioctl", or "open".

So, both domains are broken by design.

I agree with you, however, that fixing the c domain seems to be easier.

It would require some way to let the user to force the cross reference
name, like, for example:

.. c:function:: 
	:name: vidioc_ioctl 

	int ioctl( int fd, int request, struct v4l2_capability *argp )

Is it possible to extend the c-domain to do something like that and
still be backward-compatible with Sphinx 1.2?

Regards,
Mauro

Re: [PATCH 2/2] drm/doc: Fix more kerneldoc/sphinx warnings

[Mauro Carvalho Chehab]

Em Wed, 20 Jul 2016 20:35:09 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 20.07.2016 um 14:20 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > Em Tue, 19 Jul 2016 14:36:50 +0200
> > Daniel Vetter <daniel@ffwll.ch> escreveu:
> >   
> >> On Tue, Jul 19, 2016 at 01:42:55PM +0200, Daniel Vetter wrote:  
> >>> These are the leftovers I could only track down using keep_warnings =
> >>> True. For some of them we might want to update our style guide on how
> >>> to reference structures and constants, not sure ...
> >>> 
> >>> Cc: Markus Heiser <markus.heiser@darmarit.de>
> >>> Cc: Jonathan Corbet <corbet@lwn.net>
> >>> Cc: linux-doc@vger.kernel.org
> >>> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>    
> >> 
> >> Aside: With this and the latest docs-next branch from Jon it's possible to
> >> compile test doc changes (e.g. with git rebase -x) using:
> >> 
> >> $ make IGNORE_DOCBOOKS=1 SPHINXOPTS=-W htmldocs  
> > 
> > Unfortunately, we'll not get rid of Sphinx warnings any time soon.
> > 
> > The Sphinx function parser is really broken, even on version 1.4.5.
> > 
> > Every time Sphinx finds a typedef argument or return value, like here:
> > 
> > 	ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len);
> > 
> > It produces a very ugly noisy warning:
> > 
> > ./drivers/media/dvb-core/dvb_ringbuffer.h:149: WARNING: Error when parsing function declaration.
> > If the function has no return type:
> >  Error in declarator or parameters and qualifiers
> >  Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 8]
> >    ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> >    --------^
> > If the function has a return type:
> >  Error in declarator or parameters and qualifiers
> >  If pointer to member declarator:
> >    Invalid definition: Expected '::' in pointer to member (function). [error at 37]
> >      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> >      -------------------------------------^
> >  If declarator-id:
> >    Invalid definition: Expecting "," or ")" in parameters_and_qualifiers, got "*". [error at 102]
> >      ssize_t dvb_ringbuffer_pkt_read_user (struct dvb_ringbuffer * rbuf, size_t idx, int offset, u8 __user * buf, size_t len)
> >      ------------------------------------------------------------------------------------------------------^
> >   
> 
> Aaargh ... it seems you are right. 

Just sent a fix for the above:
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=docs-next&id=263bbae9c1bf6ea7c14dad8c29f9b3148b2b5de7

I was able to fix the other two typedef warnings with:
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=docs-next&id=b32909983ab03e03504bb44d5c66f44b9d57adc3

Basically, I had to:

1) Make kernel-doc ignore __user;
2) typedef the function argument for v4l2_ctrl_add_handler();
3) not let kernel-doc generate :cpp:function: for function typedefs.

With DocBook, we used kernel-doc to produce a page for typedef
functions. Now, such capability got lost. Not sure if/how
Sphinx would support it.

Thanks,
Mauro

✗ Ro.CI.BAT: failure for series starting with [1/2] doc/sphinx: Enable keep_warnings

[Patchwork]

== Series Details ==

Series: series starting with [1/2] doc/sphinx: Enable keep_warnings
URL   : https://patchwork.freedesktop.org/series/10033/
State : failure

== Summary ==

Applying: doc/sphinx: Enable keep_warnings
Applying: drm/doc: Fix more kerneldoc/sphinx warnings
fatal: sha1 information is lacking or useless (drivers/gpu/drm/drm_crtc.c).
error: could not build fake ancestor
Patch failed at 0002 drm/doc: Fix more kerneldoc/sphinx warnings
The copy of the patch that failed is found in: .git/rebase-apply/patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Re: [PATCH 1/2] doc/sphinx: Enable keep_warnings

[Markus Heiser]

Am 19.07.2016 um 13:42 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:

> Unfortunately warnings generated after parsing in sphinx can end up
> with entirely bogus files and line numbers as sources. Strangely for
> outright errors this is not a problem. Trying to convert warnings to
> errors also doesn't fix it.
> 
> The only way to get useful output out of sphinx to be able to root
> cause the error seems to be enabling keep_warnings, which inserts
> a System Message into the actual output. Not pretty at all, but I
> don't really want to fix up core rst/sphinx code, and this gets the job
> done meanwhile.

Hi Daniel,

may I misunderstood you. Did you really get more or different warnings
if you include them into the output with "keep_warnings"?

The documentation says:

  "Regardless of this setting, warnings are always written
   to the standard error stream when sphinx-build is run."

see http://www.sphinx-doc.org/en/stable/config.html#confval-keep_warnings

Or did you not run "make cleandoc" first? Sphinx caches the doctrees
and reports markup errors only when you rebuild the cache.
The cache is also rebuild if you touch one of the source, e.g.
the drivers/gpu/drm/drm_crtc.c or the rst-file where the drm_crtc.c
is referred by a kernel-doc directive .. these dependence sometimes
confuse me .. when I missed log messages, I clean the cache e.g. by 
target cleandocs.

-- Markus --
> 
> Cc: Markus Heiser <markus.heiser@darmarit.de>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
> Documentation/conf.py | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 6cc41a0555a3..a131139675cc 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -125,7 +125,7 @@ pygments_style = 'sphinx'
> #modindex_common_prefix = []
> 
> # If true, keep warnings as "system message" paragraphs in the built documents.
> -#keep_warnings = False
> +keep_warnings = True
> 
> # If true, `todo` and `todoList` produce output, else they produce nothing.
> todo_include_todos = False
> -- 
> 2.8.1
> 

Re: [PATCH 1/2] doc/sphinx: Enable keep_warnings

[Daniel Vetter]

On Tue, Jul 19, 2016 at 4:59 PM, Markus Heiser
<markus.heiser@darmarit.de> wrote:
>
> Am 19.07.2016 um 13:42 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
>
>> Unfortunately warnings generated after parsing in sphinx can end up
>> with entirely bogus files and line numbers as sources. Strangely for
>> outright errors this is not a problem. Trying to convert warnings to
>> errors also doesn't fix it.
>>
>> The only way to get useful output out of sphinx to be able to root
>> cause the error seems to be enabling keep_warnings, which inserts
>> a System Message into the actual output. Not pretty at all, but I
>> don't really want to fix up core rst/sphinx code, and this gets the job
>> done meanwhile.
>
> Hi Daniel,
>
> may I misunderstood you. Did you really get more or different warnings
> if you include them into the output with "keep_warnings"?
>
> The documentation says:
>
>   "Regardless of this setting, warnings are always written
>    to the standard error stream when sphinx-build is run."
>
> see http://www.sphinx-doc.org/en/stable/config.html#confval-keep_warnings
>
> Or did you not run "make cleandoc" first? Sphinx caches the doctrees
> and reports markup errors only when you rebuild the cache.
> The cache is also rebuild if you touch one of the source, e.g.
> the drivers/gpu/drm/drm_crtc.c or the rst-file where the drm_crtc.c
> is referred by a kernel-doc directive .. these dependence sometimes
> confuse me .. when I missed log messages, I clean the cache e.g. by
> target cleandocs.

Yes I'm aware that sphinx it's WARNINGs when doing a partially
rebuild, this is something entirely different. I didn't get more or
less warnings this way, but keep_warning = True seems to be the only
way to get reasonable information about them. Without that I get
warnings (for included kernel-doc) where the source file is the .rst
file that pulls in the kernel doc, and the line number is entirely
bogus (often past the end of the containing .rst).

With this I can at least then open the generated .html file, search
for the System Message and figure out (by looking at the surrounding
context) where the error really is from.

Strangely this only happens for WARNING. If I manged the kerneldoc
enough to upset sphinx into generating an ERROR, the line numbers and
source files are correct.

See patch 2/2 in this series for examples of such WARNINGs: Mostly
it's unbalanced _ * or `` annotations that confuse sphinx/rst a bit.
If you want to play around with the gpu sphinx conversion to reproduce
these locall you can grab the drm-intel-nightly branch from

https://cgit.freedesktop.org/drm-intel

It already includes Jon's latest docs-next branch.

Cheers, Daniel
>
> -- Markus --
>>
>> Cc: Markus Heiser <markus.heiser@darmarit.de>
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Cc: linux-doc@vger.kernel.org
>> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
>> ---
>> Documentation/conf.py | 2 +-
>> 1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> index 6cc41a0555a3..a131139675cc 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -125,7 +125,7 @@ pygments_style = 'sphinx'
>> #modindex_common_prefix = []
>>
>> # If true, keep warnings as "system message" paragraphs in the built documents.
>> -#keep_warnings = False
>> +keep_warnings = True
>>
>> # If true, `todo` and `todoList` produce output, else they produce nothing.
>> todo_include_todos = False
>> --
>> 2.8.1
>>
>



-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 1/2] doc/sphinx: Enable keep_warnings

[Daniel Vetter]

On Tue, Jul 19, 2016 at 5:25 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> On Tue, Jul 19, 2016 at 4:59 PM, Markus Heiser
> <markus.heiser@darmarit.de> wrote:
>>
>> Am 19.07.2016 um 13:42 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
>>
>>> Unfortunately warnings generated after parsing in sphinx can end up
>>> with entirely bogus files and line numbers as sources. Strangely for
>>> outright errors this is not a problem. Trying to convert warnings to
>>> errors also doesn't fix it.
>>>
>>> The only way to get useful output out of sphinx to be able to root
>>> cause the error seems to be enabling keep_warnings, which inserts
>>> a System Message into the actual output. Not pretty at all, but I
>>> don't really want to fix up core rst/sphinx code, and this gets the job
>>> done meanwhile.
>>
>> Hi Daniel,
>>
>> may I misunderstood you. Did you really get more or different warnings
>> if you include them into the output with "keep_warnings"?
>>
>> The documentation says:
>>
>>   "Regardless of this setting, warnings are always written
>>    to the standard error stream when sphinx-build is run."
>>
>> see http://www.sphinx-doc.org/en/stable/config.html#confval-keep_warnings
>>
>> Or did you not run "make cleandoc" first? Sphinx caches the doctrees
>> and reports markup errors only when you rebuild the cache.
>> The cache is also rebuild if you touch one of the source, e.g.
>> the drivers/gpu/drm/drm_crtc.c or the rst-file where the drm_crtc.c
>> is referred by a kernel-doc directive .. these dependence sometimes
>> confuse me .. when I missed log messages, I clean the cache e.g. by
>> target cleandocs.
>
> Yes I'm aware that sphinx it's WARNINGs when doing a partially
> rebuild, this is something entirely different. I didn't get more or
> less warnings this way, but keep_warning = True seems to be the only
> way to get reasonable information about them. Without that I get
> warnings (for included kernel-doc) where the source file is the .rst
> file that pulls in the kernel doc, and the line number is entirely
> bogus (often past the end of the containing .rst).
>
> With this I can at least then open the generated .html file, search
> for the System Message and figure out (by looking at the surrounding
> context) where the error really is from.
>
> Strangely this only happens for WARNING. If I manged the kerneldoc
> enough to upset sphinx into generating an ERROR, the line numbers and
> source files are correct.
>
> See patch 2/2 in this series for examples of such WARNINGs: Mostly
> it's unbalanced _ * or `` annotations that confuse sphinx/rst a bit.
> If you want to play around with the gpu sphinx conversion to reproduce
> these locall you can grab the drm-intel-nightly branch from
>
> https://cgit.freedesktop.org/drm-intel
>
> It already includes Jon's latest docs-next branch.

btw, I couldn't check this since I didn't figure out how to intercept
the parsed rst tree and view it, but I think what's going on is:
- The source file for these warnings is .rst file containing the
kernel-doc directive. This seems to be a bug in sphinx/docutils since
we never use that file name when appending files at all.
- The line number looks like it's just counting the inserted
kernel-doc lines as part of the containing .rst file. At least
changing the content_offset in nested_parse seems to suggest that this
is the start line (e.g. adding 10k there results in all bogus WARNING
line numbers being increased by 10k). And adding more blank lines at
the beginning of the inserted kernel-doc rst also increases the
reported lines. But not when inserting blank lines at the end (i.e. it
seems like it's being reset after each directive again).

All that suggest to me this is a sphinx-internal issue, and google
sugggests there's lots of errata around line reporting. Hence why I
went with this. But of course a proper fix would be awesome! Just a
bit outside of what I think I can pull off ...
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

Re: [PATCH 1/2] doc/sphinx: Enable keep_warnings

[Markus Heiser]

Hi Daniel, hi Mauro,

Am 19.07.2016 um 17:32 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:

> On Tue, Jul 19, 2016 at 5:25 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>> On Tue, Jul 19, 2016 at 4:59 PM, Markus Heiser
>> <markus.heiser@darmarit.de> wrote:
>>> 
>>> Am 19.07.2016 um 13:42 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
>>> 
>>>> Unfortunately warnings generated after parsing in sphinx can end up
>>>> with entirely bogus files and line numbers as sources. Strangely for
>>>> outright errors this is not a problem. Trying to convert warnings to
>>>> errors also doesn't fix it.
>>>> 
>>>> The only way to get useful output out of sphinx to be able to root
>>>> cause the error seems to be enabling keep_warnings, which inserts
>>>> a System Message into the actual output. Not pretty at all, but I
>>>> don't really want to fix up core rst/sphinx code, and this gets the job
>>>> done meanwhile.
>>> 
>>> Hi Daniel,
>>> 
>>> may I misunderstood you. Did you really get more or different warnings
>>> if you include them into the output with "keep_warnings"?
>>> 
>>> The documentation says:
>>> 
>>>  "Regardless of this setting, warnings are always written
>>>   to the standard error stream when sphinx-build is run."
>>> 
>>> see http://www.sphinx-doc.org/en/stable/config.html#confval-keep_warnings
>>> 
>>> Or did you not run "make cleandoc" first? Sphinx caches the doctrees
>>> and reports markup errors only when you rebuild the cache.
>>> The cache is also rebuild if you touch one of the source, e.g.
>>> the drivers/gpu/drm/drm_crtc.c or the rst-file where the drm_crtc.c
>>> is referred by a kernel-doc directive .. these dependence sometimes
>>> confuse me .. when I missed log messages, I clean the cache e.g. by
>>> target cleandocs.
>> 
>> Yes I'm aware that sphinx it's WARNINGs when doing a partially
>> rebuild, this is something entirely different. I didn't get more or
>> less warnings this way, but keep_warning = True seems to be the only
>> way to get reasonable information about them. Without that I get
>> warnings (for included kernel-doc) where the source file is the .rst
>> file that pulls in the kernel doc, and the line number is entirely
>> bogus (often past the end of the containing .rst).
>> 
>> With this I can at least then open the generated .html file, search
>> for the System Message and figure out (by looking at the surrounding
>> context) where the error really is from.
>> 
>> Strangely this only happens for WARNING. If I manged the kerneldoc
>> enough to upset sphinx into generating an ERROR, the line numbers and
>> source files are correct.
>> 
>> See patch 2/2 in this series for examples of such WARNINGs: Mostly
>> it's unbalanced _ * or `` annotations that confuse sphinx/rst a bit.
>> If you want to play around with the gpu sphinx conversion to reproduce
>> these locall you can grab the drm-intel-nightly branch from
>> 
>> https://cgit.freedesktop.org/drm-intel
>> 
>> It already includes Jon's latest docs-next branch.
> 
> btw, I couldn't check this since I didn't figure out how to intercept
> the parsed rst tree and view it, but I think what's going on is:
> - The source file for these warnings is .rst file containing the
> kernel-doc directive. This seems to be a bug in sphinx/docutils since
> we never use that file name when appending files at all.
> - The line number looks like it's just counting the inserted
> kernel-doc lines as part of the containing .rst file. At least
> changing the content_offset in nested_parse seems to suggest that this
> is the start line (e.g. adding 10k there results in all bogus WARNING
> line numbers being increased by 10k). And adding more blank lines at
> the beginning of the inserted kernel-doc rst also increases the
> reported lines. But not when inserting blank lines at the end (i.e. it
> seems like it's being reset after each directive again).

Thanks for the explanation.

> All that suggest to me this is a sphinx-internal issue, and google
> sugggests there's lots of errata around line reporting. Hence why I
> went with this. But of course a proper fix would be awesome! Just a
> bit outside of what I think I can pull off ...

It is not really a sphinx-internal issue (rather a drawback of the design).
The state machine needs a system reporter that takes the origin file
and it's line numbers as context.

I send a fix to Jon:

 http://mid.gmane.org/1469011138-12448-1-git-send-email-markus.heiser@darmarit.de

could you test this patch and send us some feedback / thanks.

One remark: The line numbers are not "perfect". This is due to the fact,
that the kernel-doc parser could not generate "perfect" line numbers 
or all extracted doc-items .. daniel knows this ;) 

If you did not find the cause of a warning in the line number given
by the warning, take a look one line or one block above and/or below,
mostly you will see the cause.

-- Markus --


> -Daniel
> -- 
> Daniel Vetter
> Software Engineer, Intel Corporation
> +41 (0) 79 365 57 48 - http://blog.ffwll.ch

Re: [PATCH 1/2] doc/sphinx: Enable keep_warnings

[Daniel Vetter]

On Wed, Jul 20, 2016 at 12:55 PM, Markus Heiser
<markus.heiser@darmarit.de> wrote:
> Hi Daniel, hi Mauro,
>
> Am 19.07.2016 um 17:32 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
>
>> On Tue, Jul 19, 2016 at 5:25 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>>> On Tue, Jul 19, 2016 at 4:59 PM, Markus Heiser
>>> <markus.heiser@darmarit.de> wrote:
>>>>
>>>> Am 19.07.2016 um 13:42 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
>>>>
>>>>> Unfortunately warnings generated after parsing in sphinx can end up
>>>>> with entirely bogus files and line numbers as sources. Strangely for
>>>>> outright errors this is not a problem. Trying to convert warnings to
>>>>> errors also doesn't fix it.
>>>>>
>>>>> The only way to get useful output out of sphinx to be able to root
>>>>> cause the error seems to be enabling keep_warnings, which inserts
>>>>> a System Message into the actual output. Not pretty at all, but I
>>>>> don't really want to fix up core rst/sphinx code, and this gets the job
>>>>> done meanwhile.
>>>>
>>>> Hi Daniel,
>>>>
>>>> may I misunderstood you. Did you really get more or different warnings
>>>> if you include them into the output with "keep_warnings"?
>>>>
>>>> The documentation says:
>>>>
>>>>  "Regardless of this setting, warnings are always written
>>>>   to the standard error stream when sphinx-build is run."
>>>>
>>>> see http://www.sphinx-doc.org/en/stable/config.html#confval-keep_warnings
>>>>
>>>> Or did you not run "make cleandoc" first? Sphinx caches the doctrees
>>>> and reports markup errors only when you rebuild the cache.
>>>> The cache is also rebuild if you touch one of the source, e.g.
>>>> the drivers/gpu/drm/drm_crtc.c or the rst-file where the drm_crtc.c
>>>> is referred by a kernel-doc directive .. these dependence sometimes
>>>> confuse me .. when I missed log messages, I clean the cache e.g. by
>>>> target cleandocs.
>>>
>>> Yes I'm aware that sphinx it's WARNINGs when doing a partially
>>> rebuild, this is something entirely different. I didn't get more or
>>> less warnings this way, but keep_warning = True seems to be the only
>>> way to get reasonable information about them. Without that I get
>>> warnings (for included kernel-doc) where the source file is the .rst
>>> file that pulls in the kernel doc, and the line number is entirely
>>> bogus (often past the end of the containing .rst).
>>>
>>> With this I can at least then open the generated .html file, search
>>> for the System Message and figure out (by looking at the surrounding
>>> context) where the error really is from.
>>>
>>> Strangely this only happens for WARNING. If I manged the kerneldoc
>>> enough to upset sphinx into generating an ERROR, the line numbers and
>>> source files are correct.
>>>
>>> See patch 2/2 in this series for examples of such WARNINGs: Mostly
>>> it's unbalanced _ * or `` annotations that confuse sphinx/rst a bit.
>>> If you want to play around with the gpu sphinx conversion to reproduce
>>> these locall you can grab the drm-intel-nightly branch from
>>>
>>> https://cgit.freedesktop.org/drm-intel
>>>
>>> It already includes Jon's latest docs-next branch.
>>
>> btw, I couldn't check this since I didn't figure out how to intercept
>> the parsed rst tree and view it, but I think what's going on is:
>> - The source file for these warnings is .rst file containing the
>> kernel-doc directive. This seems to be a bug in sphinx/docutils since
>> we never use that file name when appending files at all.
>> - The line number looks like it's just counting the inserted
>> kernel-doc lines as part of the containing .rst file. At least
>> changing the content_offset in nested_parse seems to suggest that this
>> is the start line (e.g. adding 10k there results in all bogus WARNING
>> line numbers being increased by 10k). And adding more blank lines at
>> the beginning of the inserted kernel-doc rst also increases the
>> reported lines. But not when inserting blank lines at the end (i.e. it
>> seems like it's being reset after each directive again).
>
> Thanks for the explanation.
>
>> All that suggest to me this is a sphinx-internal issue, and google
>> sugggests there's lots of errata around line reporting. Hence why I
>> went with this. But of course a proper fix would be awesome! Just a
>> bit outside of what I think I can pull off ...
>
> It is not really a sphinx-internal issue (rather a drawback of the design).
> The state machine needs a system reporter that takes the origin file
> and it's line numbers as context.
>
> I send a fix to Jon:
>
>  http://mid.gmane.org/1469011138-12448-1-git-send-email-markus.heiser@darmarit.de
>
> could you test this patch and send us some feedback / thanks.

Yup, seems to work nicely. Thanks a lot for fixing this. Jon, pls
drop/revert my hack and take Markus' proper fix instead.

> One remark: The line numbers are not "perfect". This is due to the fact,
> that the kernel-doc parser could not generate "perfect" line numbers
> or all extracted doc-items .. daniel knows this ;)
>
> If you did not find the cause of a warning in the line number given
> by the warning, take a look one line or one block above and/or below,
> mostly you will see the cause.

Hm, I think I still have a few off-by-one in the kernel-doc line
numbers. But tbh with all the intermediate layers I wasn't sure which
one is wrong and where it would need to be fixed up. But it seems like
for a bunch of cases kernel-doc reports 1 line too much.

If someone with more insight into all this would try to improve this,
I think it'd be awesome ;-)

Cheers, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 1/2] doc/sphinx: Enable keep_warnings

[Markus Heiser]

Am 20.07.2016 um 13:27 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:

> On Wed, Jul 20, 2016 at 12:55 PM, Markus Heiser
> <markus.heiser@darmarit.de> wrote:
>> Hi Daniel, hi Mauro,
>> 
>> Am 19.07.2016 um 17:32 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
>> 
>>> On Tue, Jul 19, 2016 at 5:25 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>>>> On Tue, Jul 19, 2016 at 4:59 PM, Markus Heiser
>>>> <markus.heiser@darmarit.de> wrote:
>>>>> 
>>>>> Am 19.07.2016 um 13:42 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
>>>>> 
>>>>>> Unfortunately warnings generated after parsing in sphinx can end up
>>>>>> with entirely bogus files and line numbers as sources. Strangely for
>>>>>> outright errors this is not a problem. Trying to convert warnings to
>>>>>> errors also doesn't fix it.
>>>>>> 
>>>>>> The only way to get useful output out of sphinx to be able to root
>>>>>> cause the error seems to be enabling keep_warnings, which inserts
>>>>>> a System Message into the actual output. Not pretty at all, but I
>>>>>> don't really want to fix up core rst/sphinx code, and this gets the job
>>>>>> done meanwhile.
>>>>> 
>>>>> Hi Daniel,
>>>>> 
>>>>> may I misunderstood you. Did you really get more or different warnings
>>>>> if you include them into the output with "keep_warnings"?
>>>>> 
>>>>> The documentation says:
>>>>> 
>>>>> "Regardless of this setting, warnings are always written
>>>>>  to the standard error stream when sphinx-build is run."
>>>>> 
>>>>> see http://www.sphinx-doc.org/en/stable/config.html#confval-keep_warnings
>>>>> 
>>>>> Or did you not run "make cleandoc" first? Sphinx caches the doctrees
>>>>> and reports markup errors only when you rebuild the cache.
>>>>> The cache is also rebuild if you touch one of the source, e.g.
>>>>> the drivers/gpu/drm/drm_crtc.c or the rst-file where the drm_crtc.c
>>>>> is referred by a kernel-doc directive .. these dependence sometimes
>>>>> confuse me .. when I missed log messages, I clean the cache e.g. by
>>>>> target cleandocs.
>>>> 
>>>> Yes I'm aware that sphinx it's WARNINGs when doing a partially
>>>> rebuild, this is something entirely different. I didn't get more or
>>>> less warnings this way, but keep_warning = True seems to be the only
>>>> way to get reasonable information about them. Without that I get
>>>> warnings (for included kernel-doc) where the source file is the .rst
>>>> file that pulls in the kernel doc, and the line number is entirely
>>>> bogus (often past the end of the containing .rst).
>>>> 
>>>> With this I can at least then open the generated .html file, search
>>>> for the System Message and figure out (by looking at the surrounding
>>>> context) where the error really is from.
>>>> 
>>>> Strangely this only happens for WARNING. If I manged the kerneldoc
>>>> enough to upset sphinx into generating an ERROR, the line numbers and
>>>> source files are correct.
>>>> 
>>>> See patch 2/2 in this series for examples of such WARNINGs: Mostly
>>>> it's unbalanced _ * or `` annotations that confuse sphinx/rst a bit.
>>>> If you want to play around with the gpu sphinx conversion to reproduce
>>>> these locall you can grab the drm-intel-nightly branch from
>>>> 
>>>> https://cgit.freedesktop.org/drm-intel
>>>> 
>>>> It already includes Jon's latest docs-next branch.
>>> 
>>> btw, I couldn't check this since I didn't figure out how to intercept
>>> the parsed rst tree and view it, but I think what's going on is:
>>> - The source file for these warnings is .rst file containing the
>>> kernel-doc directive. This seems to be a bug in sphinx/docutils since
>>> we never use that file name when appending files at all.
>>> - The line number looks like it's just counting the inserted
>>> kernel-doc lines as part of the containing .rst file. At least
>>> changing the content_offset in nested_parse seems to suggest that this
>>> is the start line (e.g. adding 10k there results in all bogus WARNING
>>> line numbers being increased by 10k). And adding more blank lines at
>>> the beginning of the inserted kernel-doc rst also increases the
>>> reported lines. But not when inserting blank lines at the end (i.e. it
>>> seems like it's being reset after each directive again).
>> 
>> Thanks for the explanation.
>> 
>>> All that suggest to me this is a sphinx-internal issue, and google
>>> sugggests there's lots of errata around line reporting. Hence why I
>>> went with this. But of course a proper fix would be awesome! Just a
>>> bit outside of what I think I can pull off ...
>> 
>> It is not really a sphinx-internal issue (rather a drawback of the design).
>> The state machine needs a system reporter that takes the origin file
>> and it's line numbers as context.
>> 
>> I send a fix to Jon:
>> 
>> http://mid.gmane.org/1469011138-12448-1-git-send-email-markus.heiser@darmarit.de
>> 
>> could you test this patch and send us some feedback / thanks.
> 
> Yup, seems to work nicely. Thanks a lot for fixing this. Jon, pls
> drop/revert my hack and take Markus' proper fix instead.
> 
>> One remark: The line numbers are not "perfect". This is due to the fact,
>> that the kernel-doc parser could not generate "perfect" line numbers
>> or all extracted doc-items .. daniel knows this ;)
>> 
>> If you did not find the cause of a warning in the line number given
>> by the warning, take a look one line or one block above and/or below,
>> mostly you will see the cause.
> 
> Hm, I think I still have a few off-by-one in the kernel-doc line
> numbers. But tbh with all the intermediate layers I wasn't sure which
> one is wrong and where it would need to be fixed up. But it seems like
> for a bunch of cases kernel-doc reports 1 line too much.
> 
> If someone with more insight into all this would try to improve this,
> I think it'd be awesome ;-)

It will never be "perfect" ... as far as I know, Sphinx (docutils) will
always report on the block level, not on line level of the rst-origin.

The off-by-on could be fixed, I plan to revise the kernel-doc perl script, when
we know, what we need for man-pages [1], but I will wait for Jon's and Jani's
thoughts about man pages first.  

[1] http://mid.gmane.org/2CE565E6-19D4-4835-9A32-2FCAE754B357@darmarit.de

-- Markus --

> 
> Cheers, Daniel
> -- 
> Daniel Vetter
> Software Engineer, Intel Corporation
> +41 (0) 79 365 57 48 - http://blog.ffwll.ch

Re: [PATCH 1/2] doc/sphinx: Enable keep_warnings

[Mauro Carvalho Chehab]

Em Wed, 20 Jul 2016 14:29:01 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 20.07.2016 um 13:27 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
> 
> > On Wed, Jul 20, 2016 at 12:55 PM, Markus Heiser
> > <markus.heiser@darmarit.de> wrote:  
> >> Hi Daniel, hi Mauro,
> >> 
> >> Am 19.07.2016 um 17:32 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
> >>   
> >>> On Tue, Jul 19, 2016 at 5:25 PM, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:  
> >>>> On Tue, Jul 19, 2016 at 4:59 PM, Markus Heiser
> >>>> <markus.heiser@darmarit.de> wrote:  
> >>>>> 
> >>>>> Am 19.07.2016 um 13:42 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
> >>>>>   
> >>>>>> Unfortunately warnings generated after parsing in sphinx can end up
> >>>>>> with entirely bogus files and line numbers as sources. Strangely for
> >>>>>> outright errors this is not a problem. Trying to convert warnings to
> >>>>>> errors also doesn't fix it.
> >>>>>> 
> >>>>>> The only way to get useful output out of sphinx to be able to root
> >>>>>> cause the error seems to be enabling keep_warnings, which inserts
> >>>>>> a System Message into the actual output. Not pretty at all, but I
> >>>>>> don't really want to fix up core rst/sphinx code, and this gets the job
> >>>>>> done meanwhile.  
> >>>>> 
> >>>>> Hi Daniel,
> >>>>> 
> >>>>> may I misunderstood you. Did you really get more or different warnings
> >>>>> if you include them into the output with "keep_warnings"?
> >>>>> 
> >>>>> The documentation says:
> >>>>> 
> >>>>> "Regardless of this setting, warnings are always written
> >>>>>  to the standard error stream when sphinx-build is run."
> >>>>> 
> >>>>> see http://www.sphinx-doc.org/en/stable/config.html#confval-keep_warnings
> >>>>> 
> >>>>> Or did you not run "make cleandoc" first? Sphinx caches the doctrees
> >>>>> and reports markup errors only when you rebuild the cache.
> >>>>> The cache is also rebuild if you touch one of the source, e.g.
> >>>>> the drivers/gpu/drm/drm_crtc.c or the rst-file where the drm_crtc.c
> >>>>> is referred by a kernel-doc directive .. these dependence sometimes
> >>>>> confuse me .. when I missed log messages, I clean the cache e.g. by
> >>>>> target cleandocs.  
> >>>> 
> >>>> Yes I'm aware that sphinx it's WARNINGs when doing a partially
> >>>> rebuild, this is something entirely different. I didn't get more or
> >>>> less warnings this way, but keep_warning = True seems to be the only
> >>>> way to get reasonable information about them. Without that I get
> >>>> warnings (for included kernel-doc) where the source file is the .rst
> >>>> file that pulls in the kernel doc, and the line number is entirely
> >>>> bogus (often past the end of the containing .rst).
> >>>> 
> >>>> With this I can at least then open the generated .html file, search
> >>>> for the System Message and figure out (by looking at the surrounding
> >>>> context) where the error really is from.
> >>>> 
> >>>> Strangely this only happens for WARNING. If I manged the kerneldoc
> >>>> enough to upset sphinx into generating an ERROR, the line numbers and
> >>>> source files are correct.
> >>>> 
> >>>> See patch 2/2 in this series for examples of such WARNINGs: Mostly
> >>>> it's unbalanced _ * or `` annotations that confuse sphinx/rst a bit.
> >>>> If you want to play around with the gpu sphinx conversion to reproduce
> >>>> these locall you can grab the drm-intel-nightly branch from
> >>>> 
> >>>> https://cgit.freedesktop.org/drm-intel
> >>>> 
> >>>> It already includes Jon's latest docs-next branch.  
> >>> 
> >>> btw, I couldn't check this since I didn't figure out how to intercept
> >>> the parsed rst tree and view it, but I think what's going on is:
> >>> - The source file for these warnings is .rst file containing the
> >>> kernel-doc directive. This seems to be a bug in sphinx/docutils since
> >>> we never use that file name when appending files at all.
> >>> - The line number looks like it's just counting the inserted
> >>> kernel-doc lines as part of the containing .rst file. At least
> >>> changing the content_offset in nested_parse seems to suggest that this
> >>> is the start line (e.g. adding 10k there results in all bogus WARNING
> >>> line numbers being increased by 10k). And adding more blank lines at
> >>> the beginning of the inserted kernel-doc rst also increases the
> >>> reported lines. But not when inserting blank lines at the end (i.e. it
> >>> seems like it's being reset after each directive again).  
> >> 
> >> Thanks for the explanation.
> >>   
> >>> All that suggest to me this is a sphinx-internal issue, and google
> >>> sugggests there's lots of errata around line reporting. Hence why I
> >>> went with this. But of course a proper fix would be awesome! Just a
> >>> bit outside of what I think I can pull off ...  
> >> 
> >> It is not really a sphinx-internal issue (rather a drawback of the design).
> >> The state machine needs a system reporter that takes the origin file
> >> and it's line numbers as context.
> >> 
> >> I send a fix to Jon:
> >> 
> >> http://mid.gmane.org/1469011138-12448-1-git-send-email-markus.heiser@darmarit.de
> >> 
> >> could you test this patch and send us some feedback / thanks.  
> > 
> > Yup, seems to work nicely. Thanks a lot for fixing this. Jon, pls
> > drop/revert my hack and take Markus' proper fix instead.
> >   
> >> One remark: The line numbers are not "perfect". This is due to the fact,
> >> that the kernel-doc parser could not generate "perfect" line numbers
> >> or all extracted doc-items .. daniel knows this ;)
> >> 
> >> If you did not find the cause of a warning in the line number given
> >> by the warning, take a look one line or one block above and/or below,
> >> mostly you will see the cause.  
> > 
> > Hm, I think I still have a few off-by-one in the kernel-doc line
> > numbers. But tbh with all the intermediate layers I wasn't sure which
> > one is wrong and where it would need to be fixed up. But it seems like
> > for a bunch of cases kernel-doc reports 1 line too much.
> > 
> > If someone with more insight into all this would try to improve this,
> > I think it'd be awesome ;-)  
> 
> It will never be "perfect" ... as far as I know, Sphinx (docutils) will
> always report on the block level, not on line level of the rst-origin.

Well, with kernel-doc and DocBook, the error reports were always with
some offset, but I don't think that this is a big issue. I mean: if it
points to the right documentation markup block at the source file, it
is not hard to identify where the bugs are.

> 
> The off-by-on could be fixed, I plan to revise the kernel-doc perl script, when
> we know, what we need for man-pages [1], but I will wait for Jon's and Jani's
> thoughts about man pages first.  
> 
> [1] http://mid.gmane.org/2CE565E6-19D4-4835-9A32-2FCAE754B357@darmarit.de
> 
> -- Markus --
> 
> > 
> > Cheers, Daniel
> > -- 
> > Daniel Vetter
> > Software Engineer, Intel Corporation
> > +41 (0) 79 365 57 48 - http://blog.ffwll.ch  
> 



Thanks,
Mauro

Re: [PATCH 1/2] doc/sphinx: Enable keep_warnings

[Jonathan Corbet]

On Tue, 19 Jul 2016 13:42:54 +0200
Daniel Vetter <daniel.vetter@ffwll.ch> wrote:

> Unfortunately warnings generated after parsing in sphinx can end up
> with entirely bogus files and line numbers as sources. Strangely for
> outright errors this is not a problem. Trying to convert warnings to
> errors also doesn't fix it.
> 
> The only way to get useful output out of sphinx to be able to root
> cause the error seems to be enabling keep_warnings, which inserts
> a System Message into the actual output. Not pretty at all, but I
> don't really want to fix up core rst/sphinx code, and this gets the job
> done meanwhile.

I'll go ahead and apply this.  It *would* be nice, someday, to figure out
how to get proper info out for warnings directly, but until somebody gets
there...

Thanks,

jon