SPHINX: no structured comments

SPHINX: no structured comments

[Stephan Mueller]

Hi,

I am converting the kernel crypto API DocBook into Sphinx. The conversion is 
complete, but I am having difficulties finding the cause for the following 
notification obtained during the Sphinx compilation:

./include/linux/crypto.h:1: warning: no structured comments found

I am unsure what is wrong in line 1 of the mentioned header.

Thanks a lot
Stephan

Re: SPHINX: no structured comments

[Markus Heiser]

Am 15.10.2016 um 17:05 schrieb Stephan Mueller <smueller@chronox.de>:

> Hi,
> 
> I am converting the kernel crypto API DocBook into Sphinx. The conversion is 
> complete, but I am having difficulties finding the cause for the following 
> notification obtained during the Sphinx compilation:
> 
> ./include/linux/crypto.h:1: warning: no structured comments found
> 
> I am unsure what is wrong in line 1 of the mentioned header.
> 
> Thanks a lot
> Stephan

Hi Stephan,

I suppose you have a typo in one of your kernel-doc
directives. E.g.::

 .. kernel-doc:: include/linux/crypto.h
     :functions: fooTypo

will produce those error messages:

 $ ./scripts/kernel-doc -function fooTypo  -rst ./include/linux/crypto.h
 ./include/linux/crypto.h:1: warning: no structured comments found

hope that helps.

FYI:

IMO the kernel-doc parser in the kernel sources is lazy.  In my
linuxdoc project you will find a more enthusiastic one with a
lint command.

 https://return42.github.io/linuxdoc

Even if this kernel-doc parser is not (yet) a part of the kernel
source tree, the kernel-lintdoc command might be helpful
finding (more) issues

 https://return42.github.io/linuxdoc/cmd-line.html#kernel-lintdoc

The installation is quite simple:

 pip install git+http://github.com/return42/linuxdoc.git

The next hint might be a bit to late for you, but there is a
*automatic* DocBook to reST migration of the crypto API:

 https://github.com/return42/sphkerneldoc/tree/master/doc/Documentation/books_migrated/crypto-API

This migration is done with the my dbxm2rst project:

 https://return42.github.io/dbxml2rst/

If you need more help or want to migrate more DocBook
documentation to reST ... don't hesitate to contact me
(on the ML or directly / de-de ;-)

-- Markus --

Re: SPHINX: no structured comments

[Stephan Mueller]

Am Samstag, 15. Oktober 2016, 18:12:36 CEST schrieb Markus Heiser:

Hi Markus,

> I suppose you have a typo in one of your kernel-doc
> directives. E.g.::
> 
>  .. kernel-doc:: include/linux/crypto.h
> 
>      :functions: fooTypo
> 
> will produce those error messages:
> 
>  $ ./scripts/kernel-doc -function fooTypo  -rst ./include/linux/crypto.h
>  ./include/linux/crypto.h:1: warning: no structured comments found
> 
> hope that helps.

Thanks for the hint. The issue was a removed API call.

...
> 
> The next hint might be a bit to late for you, but there is a
> *automatic* DocBook to reST migration of the crypto API:
> 
>  https://github.com/return42/sphkerneldoc/tree/master/doc/Documentation/book
> s_migrated/crypto-API

Thanks for the hint. You are right, it is a bit late, but the DocBook to 
Sphinx converter helped me.

With Sphinx now, I also split up the document into more manageable chunks and 
fixed some small issues.

Thanks for your help.

Ciao
Stephan