Re: [Discuss-gnuradio] Documentation generation using Sphinx

[Martin Braun]

On Wed, Feb 29, 2012 at 08:05:46PM -0700, Ben Reynwar wrote:
> 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.

I think it's great! Something like this is really missing, especially if
you're used to browsing the official Python docs; in that case Sphinx is
probably a sight you're used to.

One thing I don't love is this:
<snip>
gnuradio.gr.glfsr_source_b Creates a glfsr_source_b blocksk.
gnuradio.gr.glfsr_source_f Creates a glfsr_source_f block.
gnuradio.gr.lfsr_32k_source_s Creates a lfsr_32k_source_s block.
gnuradio.gr.nowull_source Creates a null_source block.
gnuradio.gr.noise_source_c Createseates a noise_source_c block.
gnuradio.gr.noise_source_f Creates a noise_source_fse_source_f block.
</snip>

This contains zero information. To get to the interesting information, I
have to first click the entry. If I try help(gr.glfsr_source_b) on my
machine, I get the interesting part of the docs straight away ("Galois
LFSR pseudo-random source generating float outputs -1.0 - 1.0." instead
of "Creates a glfsr_source_b block").

In the gr.digital package, this isn't quite as bad. Perhaps a documentation
"standard" wouldn't be a bad idea (but none of this has anything to do
with Sphinx, I guess ;).

MB

-- 
Karlsruhe Institute of Technology (KIT)
Communications Engineering Lab (CEL)

Dipl.-Ing. Martin Braun
Research Associate

Kaiserstraße 12
Building 05.01
76131 Karlsruhe

Phone: +49 721 608-43790
Fax: +49 721 608-46071
www.cel.kit.edu

KIT -- University of the State of Baden-Württemberg and
National Laboratory of the Helmholtz Association

pgpnsy91mb_MH.pgp
Description: PGP signature