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
pgpLVxqMZsetb.pgp
Description: PGP signature
_______________________________________________ Discuss-gnuradio mailing list [email protected] https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
