Re: [Discuss-gnuradio] Documentation generation using Sphinx

[Ben Reynwar]

Just to clarify, I'm not suggesting we get rid of the Doxygen
documentation.  I think it documents the C++ side of things really
well.  What I'm suggesting is that we have two sets of documentation.
Doxygen-generated docs for the C++ stuff,  and sphinx-generated docs
for the python interface.

At the moment the subheaders are coming from the \ingroup tag
indirectly, in that I use that them to generate the initial
documentation, but it won't update automatically if they are changed.
I think automating the documentation generation to the level where
these would update automatically would complicate things more than it
would help.

I'll continue extending and tidying up the documentation and let you
know when it's at a more presentable point.

Cheers,
Ben

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
>