Re: [Discuss-gnuradio] Documentation generation using Sphinx

[Tom Rondeau]

On Thu, Mar 1, 2012 at 12:16 PM, Ben Reynwar <address@hidden> wrote:

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.

It looks like you have all of the C++ blocks moved over into the Sphinx-generated docs, too, though, which duplicates what's in Doxygen. Having two sets of documentation seems a bit confusing to me, but I can see how a C++-only developer might get confused about stuff mentioned in the manual that's only available if using Python.

So with the latter argument in mind, I guess we could (and maybe should) have separate documents for the two cases.

 

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 think Josh worked out in cmake how to regenerate the swigdoc output if any of the files are changed, so it seems like a similar thing should be applicable here, too.

 

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
>