On Thu, Mar 1, 2012 at 2:21 PM, Ben Reynwar <b...@reynwar.net> wrote:
> On Thu, Mar 1, 2012 at 12:05 PM, Tom Rondeau <t...@trondeau.com> wrote: > > On Thu, Mar 1, 2012 at 2:00 PM, Ben Reynwar <b...@reynwar.net> wrote: > >> > >> On Thu, Mar 1, 2012 at 11:20 AM, Tom Rondeau <t...@trondeau.com> wrote: > >> > On Thu, Mar 1, 2012 at 12:16 PM, Ben Reynwar <b...@reynwar.net> 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. We just want to automate any document generation as much as possible so it's always up-to-date when you build it. Tom > >> > >> >> > >> >> 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 <t...@trondeau.com> > 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 <martin.br...@kit.edu > > > >> >> > 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 > >> >> >> Discuss-gnuradio@gnu.org > >> >> >> https://lists.gnu.org/mailman/listinfo/discuss-gnuradio > >> >> >> > >> >> > > >> >> > > >> >> > _______________________________________________ > >> >> > Discuss-gnuradio mailing list > >> >> > Discuss-gnuradio@gnu.org > >> >> > https://lists.gnu.org/mailman/listinfo/discuss-gnuradio > >> >> > > >> > > >> > > > > > >
_______________________________________________ Discuss-gnuradio mailing list Discuss-gnuradio@gnu.org https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
