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