Messages in this thread | | | Subject | Re: Kernel docs: muddying the waters a bit | From | Markus Heiser <> | Date | Wed, 4 May 2016 17:55:05 +0200 |
| |
Am 04.05.2016 um 15:43 schrieb Daniel Vetter <daniel@ffwll.ch>:
> On Wed, May 04, 2016 at 02:40:29PM +0200, Markus Heiser wrote: >>> On Wed, 04 May 2016, Markus Heiser <markus.heiser@darmarit.de> wrote: >>> I'd be *very* hesitant about adding the kind of things you do in >>> reformat_block_rst to kernel-doc. IMO the extraction from kernel-doc >>> comments must be as simple as possible with basically pass-through of >>> the comment blocks to sphinx. >> >> Right, but you forgot, that the current markup in the source code comments >> is based on the kernel-doc-nano-HOWTO and I guess no one will migrate all >> these source code comments to reST markup ;-) >> >> So there is a need to differentiate between *vintage* kernel-doc markup >> and reST markup. >> >> My suggestion is to add a tag to the comments, here a short example >> what this might look like. >> >> <vintage-comment-SNIP> -------------- >> /** >> * drm_minor_release - Release DRM minor >> * @minor: Pointer to DRM minor object >> * >> * Release a minor that was previously acquired via drm_minor_acquire(). >> */ >> <vintage-comment-SNAP> -------------- >> >> in short: the vintage style does not need any change and >> comments with reST markup has a tag ":reST:" in the first >> line(s) ... >> >> <reST-comment-SNIP> -------------- >> /** >> * :reST: >> * >> * .. c:function:: void drm_minor_release(struct drm_minor *minor) >> * >> * Release DRM minor >> * >> * :param struct drm_minor \*minor: Pointer to DRM minor object >> * >> */ >> <reST-comment-SNAP> -------------- >> >> Comments with the ":reST:" tag could be exported and pass-through >> to sphinx. >> >>> Specifically, do not attempt to detect and >>> parse elements like lists in kernel-doc. >> >> If your markup in the comments is plain reST, no need to parse, but there >> are markups in the (vintage) comments which made use of individual >> text-markups, e.g. the markup of lists or ASCII-art. >> >> This individual text-markups has not been converted/rendered in the docbook >> output, but I wanted to convert this individuals to reST, to render them in >> Sphinx. > > I think we need to unconfuse what's current standardize kerneldoc markup. > There's three bits: > - The header with the one-liner and parameters, i.e.
OK, forget my <reST-comment-SNAP> example, I don't really want to promote this way ... I agree, it is better to stay with standardize kernel-doc markup and provide a "pass through" for the section-content (even if it is mixing markups).
Am 04.05.2016 um 15:41 schrieb Jani Nikula <jani.nikula@intel.com>:
> Kernel-doc the tool should continue to parse kernel-doc comments at the > high level like they currently are, according to the kernel-doc > howto.
The requirement was unclear for me, thanks to Daniel and Jani for clarifying this.
Am 04.05.2016 um 15:43 schrieb Daniel Vetter <daniel@ffwll.ch>:
> This is already used widely in kerneldoc included by gpu.tmpl, and > currently it's asciidoc. Those lists and asciiarts though are _not_ > standard kerneldoc at all. But imo any doc toolchain improvement should > integrate along those lines. > > For reference, this is what it's supposed to look like with the asciidoc > support enabled: > > https://dri.freedesktop.org/docs/drm/API-struct-drm-display-mode.html > > Fyi those hacked-up patches to make this happen are available in > > https://cgit.freedesktop.org/drm-intel/log/?h=topic/kerneldoc >
Correct my, if I'am wrong. I'am a bit unfamiliar with DOCPROC in particular with your "MARKDOWNREADY := gpu.xml" process.
As I understood, you convert markdown to docbook within the kernel-doc script using pandoc's executable? ... I don't face this topic. With my modification of kernel-doc I produced pure reST markup from standardize kernel-doc markup, no intermediate steps or tools required.
Am 04.05.2016 um 15:41 schrieb Jani Nikula <jani.nikula@intel.com>:
> Overall I think we should promote fixing those in the kernel-doc > comments. Trying to guesswork in kernel-doc tool will leave the source > littered with bad examples that get proliferated all around. Instead of > gradually fixing things, we'll end up gradually messing things up even > more.
I agree with you, lets drop the reformat_block_rst from my kernel-doc script:
* https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc#L1736
and we should have a plain "pass through".
Am 04.05.2016 um 17:09 schrieb Jonathan Corbet <corbet@lwn.net>:
> I think all of this makes sense. It would be really nice to have the > directives in the native sphinx language like that. I *don't* think we > need to aim for that at the outset; the docproc approach works until we can > properly get rid of it. What would be *really* nice would be to get > support for the kernel-doc directive into the sphinx upstream.
No need for kernel-doc directive in sphinx upstream, later it will be an extension which could be installed by a simple command like "pip install kernel-doc-extensions" or similar.
I develop these required extension (and more) within my proof of concept on github ... this takes time ... if I finished all my tests and all is well, I will build the *kernel-doc-extensions* package and deploy it on https://pypi.python.org/pypi from where everyone could install this with "pip".
At this time I see only one change/merge to the linux upstream, this is my modification of the kernel-doc script to get a proper reST output.
But my recommendation is not to merge anything in a hurry.
--Markus--
| |