Re: [Discuss-gnuradio] Documentation generation using Sphinx

[Ben Reynwar]

On Thu, Mar 1, 2012 at 12:05 PM, Tom Rondeau <address@hidden> wrote:
> On Thu, Mar 1, 2012 at 2:00 PM, Ben Reynwar <address@hidden> wrote:
>>
>> 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:
>> >>
>> >> 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.
>
>
> Ok, I see. Is there a way to just stick all of these into an "uncategorized"
> section? We could then edit the offenders to give them a proper group.
>
> Tom
>

I you're really keen on getting the block categorization automated
then I'm sure I can come up with a way.  Sphinx is extendable so I
would probably create a new sphinx markup command that includes all
the blocks for a given category.  In this way the sphinx source file
would still be manually edited if you want to add a new utility
function, or python hierarchical block to the documentation but the
swiged signal processing blocks would be added automatically.

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