Re: [Discuss-gnuradio] Documentation generation using Sphinx

[Michael Dickens]

Hi Ben - I like the look of the generated HTML much more than that done by 
Doxygen.  That said, there is a serious deficiency ... maybe this is the 
"continuing down this path" of which you speak: Is there any way for specific 
blocks to get sphinx to generate actual arguments?  
"gnuradio.gr.fft_filter_ccc(*args, **kwargs)" isn't very useful, but 
"gnuradio.gr.fft_filter_ccc(vector < gr_complex > taps)" would be (if that's 
what the actual prototype is; I don't remember it exactly right now).  Nice 
job; I say to keep it up ... - MLD

On Feb 29, 2012, at 3:26 PM, Ben Reynwar wrote:
> Every 6 months or so I have a crack at getting some python level
> documentation working.  In this attempt, I've generated documentation
> for the gr and digital modules using sphinx.
> 
> The generated html is at:
> http://www.reynwar.net/gnuradio/sphinx/
> 
> Source for the generated documentation is at:
> https://github.com/benreynwar/gnuradio/tree/sphinx/docs/sphinx/source
> 
> The documentation generation is semi-automatic.  I created files
> containing lists of the objects we want to document, and organized
> them into categories.  The actual documentation itself was pulled from
> the docstrings automatically.  It would be necessary to manually edit
> files when new blocks or other objects are added, so there is a danger
> that this kind of documentation could become incomplete, however
> because the content is taken from the docstrings it should remain
> accurate, if not complete.
> 
> Are there any objections to me continuing down this path of
> documentation generation?  Any suggestions?