On Thu, Mar 1, 2012 at 12:16 PM, Ben Reynwar <b...@reynwar.net> 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 <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
