On Thu, 23 May 2019, Jonathan Corbet <corbet@xxxxxxx> wrote: > With Sphinx 2.0 (or prior versions with the deprecation warnings fixed) the > docs build fails with: > > Documentation/gpu/i915.rst:403: WARNING: Title level inconsistent: > > Global GTT Fence Handling > ~~~~~~~~~~~~~~~~~~~~~~~~~ > > reST markup error: > Documentation/gpu/i915.rst:403: (SEVERE/4) Title level inconsistent: > > I "fixed" it by changing the subsections in i915.rst, but that didn't seem > like the correct change. It turns out that a couple of i915 files create > their own subsections in kerneldoc comments using apostrophes as the > heading marker: > > Layout > '''''' > > That breaks the normal subsection marker ordering, and newer Sphinx is > rather more strict about enforcing that ordering. So fix the offending > comments to make Sphinx happy. > > (This is unfortunate, in that kerneldoc comments shouldn't need to be aware > of where they might be included in the heading hierarchy, but I don't see > a better way around it). > > Signed-off-by: Jonathan Corbet <corbet@xxxxxxx> > --- > [If I can possibly get an ack for this, I would like to send it up soon > with the other Sphinx-related fixes.] Thanks, whatever works, Acked-by: Jani Nikula <jani.nikula@xxxxxxxxx> > > drivers/gpu/drm/i915/i915_reg.h | 6 +++--- > drivers/gpu/drm/i915/intel_workarounds.c | 2 +- > 2 files changed, 4 insertions(+), 4 deletions(-) > > diff --git a/drivers/gpu/drm/i915/i915_reg.h b/drivers/gpu/drm/i915/i915_reg.h > index b74824f0b5b1..249d35c12a75 100644 > --- a/drivers/gpu/drm/i915/i915_reg.h > +++ b/drivers/gpu/drm/i915/i915_reg.h > @@ -35,7 +35,7 @@ > * macros. Do **not** mass change existing definitions just to update the style. > * > * Layout > - * '''''' > + * ~~~~~~ > * > * Keep helper macros near the top. For example, _PIPE() and friends. > * > @@ -79,7 +79,7 @@ > * style. Use lower case in hexadecimal values. > * > * Naming > - * '''''' > + * ~~~~~~ > * > * Try to name registers according to the specs. If the register name changes in > * the specs from platform to another, stick to the original name. > @@ -97,7 +97,7 @@ > * suffix to the name. For example, ``_SKL`` or ``_GEN8``. > * > * Examples > - * '''''''' > + * ~~~~~~~~ > * > * (Note that the values in the example are indented using spaces instead of > * TABs to avoid misalignment in generated documentation. Use TABs in the > diff --git a/drivers/gpu/drm/i915/intel_workarounds.c b/drivers/gpu/drm/i915/intel_workarounds.c > index 9682dd575152..6decd432f4d3 100644 > --- a/drivers/gpu/drm/i915/intel_workarounds.c > +++ b/drivers/gpu/drm/i915/intel_workarounds.c > @@ -37,7 +37,7 @@ > * costly and simplifies things. We can revisit this in the future. > * > * Layout > - * '''''' > + * ~~~~~~ > * > * Keep things in this file ordered by WA type, as per the above (context, GT, > * display, register whitelist, batchbuffer). Then, inside each type, keep the -- Jani Nikula, Intel Open Source Graphics Center _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/intel-gfx
