Re: [Discuss-gnuradio] Documentation generation using Sphinx

[Tom Rondeau]

Ben,

Yes, I was definitely confused. I think this is promising. So you're saying that it gets populated by Doxygen markup that's already in the files? So we don't have to redo any of the documentation that we already have, right?

Also, I've been adding Doxygen pages (.dox files) with more descriptions, examples, etc. into the Doxygen manual. I really like this way as it keeps things all together as part of the code and the automatically generated manual. If we can keep these as well, that's great. And I'm assuming that the subheaders like "Signal Sources" and "Signal Sinks" are taken from the \ingroup tags?

Another thing that I've been doing with the Doxygen manual is keeping older versions of it alive on the website so that people can look at the manual for their particular version of GNU Radio (http://gnuradio.org/redmine/projects/gnuradio/wiki/Old-docs). So again, I'd like to be able to easily host these. Looking at your URL, it looks like it'll be simple.

So yes, I say continue on this path. Taking what Martin and Michael said about fixing some of the structure/styling would really help it, too.

Thanks!

Tom

On Thu, Mar 1, 2012 at 5:42 AM, Martin Braun <address@hidden> wrote:

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


_______________________________________________
Discuss-gnuradio mailing list
address@hidden
https://lists.gnu.org/mailman/listinfo/discuss-gnuradio