>>
>> I'll continue extending and tidying up the documentation and let you
>> know when it's at a more presentable point.
>>
>> Cheers,
>> Ben
>
>
> Thanks,
> Tom
>
>>
>> On Thu, Mar 1, 2012 at 7:57 AM, Tom Rondeau <
address@hidden> wrote:
>> > 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
>> >>
>> >
>> >
>> > _______________________________________________
>> > Discuss-gnuradio mailing list
>> >
address@hidden
>> >
https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
>> >
>
>