Re: [Discuss-gnuradio] Documentation generation using Sphinx

[Ben Reynwar]

On Wed, Feb 29, 2012 at 6:50 PM, Tom Rondeau <address@hidden> wrote:
> On Wed, Feb 29, 2012 at 3:26 PM, Ben Reynwar <address@hidden> wrote:
>>
>> Hi all,
>>
>> Every 6 months or so I have a crack at getting some python level
>> documentation working.  In this attempt, I've generated documentation
>> for the gr and digital modules using sphinx.
>>
>> The generated html is at:
>> http://www.reynwar.net/gnuradio/sphinx/
>>
>> Source for the generated documentation is at:
>> https://github.com/benreynwar/gnuradio/tree/sphinx/docs/sphinx/source
>>
>> The documentation generation is semi-automatic.  I created files
>> containing lists of the objects we want to document, and organized
>> them into categories.  The actual documentation itself was pulled from
>> the docstrings automatically.  It would be necessary to manually edit
>> files when new blocks or other objects are added, so there is a danger
>> that this kind of documentation could become incomplete, however
>> because the content is taken from the docstrings it should remain
>> accurate, if not complete.
>>
>> Are there any objections to me continuing down this path of
>> documentation generation?  Any suggestions?
>>
>> Cheers,
>> Ben
>
>
> I'm a bit confused, Ben. What does this do that we aren't doing in the
> swig_docs work we put in last year?
>
> Tom
>

The swig_doc stuff got all the documentation from doxygen into the
python docstrings.

What I'm trying to do with this is to create some nice documentation
that we can put online that serves as a reference for someone
developing with gnuradio in python.  I had a go at this last year, but
didn't get very far, partly because the swig_doc stuff wasn't fully
working.  Now that the swig_docs is all sorted, it felt like a good
time to push with the documentation again.

Stuff that needs work is
 - (*args, **kwargs) appears for some blocks but for others it
displays the parameters correctly.
 - sometimes it displays __dummy_0_ for parameter types
 - there a bunch of subpackages which I haven't touched yet

It'll take a bit of work to get this done, and unless people are on
board with the general concept of using sphinx to generate this
documentation, it doesn't make sense for me to spend time doing it,
which is why I'm bugging you all now with some half-finished
documentation.

Cheers,
Ben