Hi Jani, Am 04.05.2016 um 11:58 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > On Wed, 04 May 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: >> but I think this will not by very helpful, as long as you miss >> a similar ".tmpl" workflow for reST documents. >> >> I'am working on a reST directive (named: "kernel-doc") to provide a >> similar ".tmpl" workflow within plain reST. The first step towards >> is done with (my) modified kernel-doc script ... >> >> * https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc#L1736 >> >> which produce reST from source code comments. E.g. this content is >> generated with it. > > What do you mean by ".tmpl workflow"? Sorry for bad naming, I addressed the DOCPROC build process which builds the .xml files from .tmpl files ... <SNIP> ---- ### # The build process is as follows (targets): # (xmldocs) [by docproc] # file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto] # +--> file.pdf (pdfdocs) [by db2pdf or xmlto] # +--> DIR=file (htmldocs) [by xmlto] # +--> man/ (mandocs) [by xmlto] .... ### # DOCPROC is used for two purposes: # 1) To generate a dependency list for a .tmpl file # 2) To preprocess a .tmpl file and call kernel-doc with # appropriate parameters. # The following rules are used to generate the .xml documentation # required to generate the final targets. (ps, pdf, html). <SNAP> ----- The DOCPROC markup directives are described in the kernel-doc-nano-HOWTO: https://github.com/torvalds/linux/blob/master/Documentation/kernel-doc-nano-HOWTO.txt#L332 My aim is to implement a reST-directive which is similar. E.g: <XML-SNIP> ----- <sect2> <title>Device Instance and Driver Handling</title> !Pdrivers/gpu/drm/drm_drv.c driver instance overview !Edrivers/gpu/drm/drm_drv.c </sect2> <sect2> <XML-SNAP> ----- In reST the directive might look like: <reST-SNIP> ----- Device Instance and Driver Handling =================================== .. kernel-doc:: drivers/gpu/drm/drm_drv.c :doc: driver instance overview :exported: <reST-SNAP> ----- > 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. E.g. compare the member & description section of struct drm-display-mode ... DocBook: * https://www.kernel.org/doc/htmldocs/gpu/API-struct-drm-display-mode.html kernel-doc reST with the additional reformat_block_rst function: * http://return42.github.io/sphkerneldoc/linux_src_doc/include/drm/drm_modes_h.html#struct-drm-display-mode -- Markus-- > -- > Jani Nikula, Intel Open Source Technology Center > -- > To unsubscribe from this list: send the line "unsubscribe linux-media" in > the body of a message to majordomo@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
