Python docs

GNU Radio
1

Good day.

I’d like to know more about the Python doc problem.

http://lists.gnu.org/archive/html/discuss-gnuradio/2005-01/msg00249.html

From what I can tell, generating python docs for gnuradio is an outstanding
task

http://www.comsec.com/wiki?SuggestedProjects

I say this because I do not see xsltproc, for example, called anywhere
during build, and I think if this problem were already solved, I
probably
would.

While I cannot yet volunteer to work on this problem, a bit of status on
where it is would be helpful.

Some things I believe and/or have executed:

  • Being new to swig and python and its uses in given situations, I’m
    still a
    bit disoriented wrto which gnuradio-core (“core”) piece dovetails into
    what
    other piece.

I think it goes like this:

In the beginning, there was C++. From that follows python interfaces
into
C++ via swig. From there we find utility python code in the core
written by
some human and not a code generating tool. And from there we find
python
application code here and there.

  • True or false (and why so either way): the documentation task above
    must
    be solved before we can produce, presumably with epydoc, html docs for
    any
    core python code.

  • Having compiled the core with --enable-doxygen, I notice that there
    are
    xml files in the output, presumably the ones mentioned in the mailing
    list
    post.

  • I notice some %feature(“autodoc”,“1”) instances in some .i swig files.
    It
    appears we are incrementally solving the problem that is the subject of
    the
    mailing list posting above.

  • I see many .i files that do not contain “autodoc”/“docstring”
    directives.
    Not sure why, or what the implications are. (Notice how
    this can mean “I disagree with what I see” or “Someone tell me why I see
    what I see, because I just don’t know”. I mean the latter.).

  • assuming we get to swig_doc.i files mentioned in the post, would there
    be
    one swig_doc.i file for every other .i file in the core?

  • a general backing question: a python module can have code that
    originates
    in high level python code (a .py file) as well as code that comes to us
    by
    way of a swig interface. gnuradio.gr, e.g., has a flow_graph via
    ‘native’
    python code as well as a file_sink that comes to us via swig.
    Presumably we
    lack input that can generate docs for that swig interface object.

  • if this problem were already solved, can I get an example of an html
    file
    that would exist as a result? Just the file name, not the contents.

Thank you.