• Daniel Vetter's avatar
    doc/sphinx: Track line-number of starting blocks · d90368f2
    Daniel Vetter authored
    Design is pretty simple: kernel-doc inserts breadcrumbs with line
    numbers, and sphinx picks them up. At first I went with a sphinx
    comment, but inserting those at random places seriously upsets the
    parser, and must be filtered. Hence why this version now uses "#define
    LINEO " since one of these ever escape into output it's pretty clear
    there is a bug.
    
    It seems to work well, and at least the 2-3 errors where sphinx
    complained about something that was not correct in kernel-doc text the
    line numbers matched up perfectly.
    
    v2: Instead of noodling around in the parser state machine, create
    a ViewList and parse it ourselves. This seems to be the recommended
    way, per Jani's suggestion.
    
    v3:
    - Split out ViewList pach. Splitting the kernel-doc changes from the
      sphinx ones isn't possible, since emitting the LINENO lines wreaks
      havoc with the rst formatting. We must filter them.
    
    - Improve the regex per Jani's suggestions, and compile it just once
      for speed.
    
    - Now that LINENO lines are eaten, also add them to function parameter
      descriptions. Much less content and offset than for in-line struct
      member descriptions, but still nice to know which exact continuation
      line upsets sphinx.
    
    - Simplify/clarify the line +/-1 business a bit.
    
    v4: Split out the scripts/kernel-doc changes and make line-numbers
    opt-in, as suggested by Jani.
    
    Cc: Jani Nikula <jani.nikula@intel.com>
    Cc: linux-doc@vger.kernel.org
    Cc: Jonathan Corbet <corbet@lwn.net>
    Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
    Signed-off-by: default avatarJani Nikula <jani.nikula@intel.com>
    d90368f2
kernel-doc.py 4.78 KB