Re: [Discuss-gnuradio] Documentation generation using Sphinx

[Ben Reynwar]

On Thu, Mar 1, 2012 at 11:20 AM, Tom Rondeau <address@hidden> wrote:
> 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.
>
Yeah, ideally it would be nice to have one set of documentation that
covers the C++ and python levels, but I can't think of a way to do
that, that doesn't do a bad job of one or the other.  Creating two
sets of documentation is the path of least resistance to finally
getting a reference for the python interface out there.

>>
>> 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.

Although I generated the source files for sphinx to avoid tediousness,
I also did a bunch of manual editing afterwards.   There are lots of
objects in the python modules that aren't swiged signal processing
blocks and so don't have \ingroup tags, for example python
hierarchical blocks, constellation objects, utility functions, and
random internal stuff that is floating around in the module namespace.
 Automating the decision on whether to include or exclude these
objects in the documentation, and what category to place them in would
be non-trivial.  This is why using a tool like epydoc does not work
for us.

At the moment, when the html is regenerated, the docstrings themselves
will be updated, but the organization of the objects into categories
will not change unless the sphinx source files have been manually
edited.

>
>>
>> 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
>> >
>
>