Orange Forum • View topic - More info in docstrings

More info in docstrings

Discussions about new ideas and features you would like to see in Orange.
(Archived/read-only, please use our ticketing system for your wishes and their discussion.)
Forum rules
(Archived/read-only, please use our ticketing system for your wishes and their discussion.)

More info in docstrings

Postby neuroman » Tue Jan 20, 2009 15:14

I would love to see more information concerning the classes, functions, and examples to go in to the docstrings. I use interactive help a lot and it would be great to be able to get that information quickly from the command line rather than to have to try to find simple information on the web site.

This way, you can auto-generate most of the online documentation and when you make changes to the source, you can easily update the docs to reflect that and regenerate the online docs too.

This is what interactive help looks like now:
Code: Select all
In [16]: ?orange.saveC45
Type:      builtin_function_or_method
Base Class:   <type 'builtin_function_or_method'>
String Form:   <built-in function saveC45>
Namespace:   Interactive
Docstring:
    (filename, examples) -> None

In [21]: ?orngClustering.DendrogramPlot
Type:      type
Base Class:   <type 'type'>
String Form:   <class 'orngClustering.DendrogramPlot'>
Namespace:   Interactive
File:      /usr/lib/python2.5/site-packages/orange/orngClustering.py
Docstring:
    <no docstring>

Constructor information:
Definition:   orngClustering.DendrogramPlot(self, tree, data=None, labels=None, width=None, height=None, treeAreaWidth=None, textAreaWidth=None, matrixAreaWidth=None, fontSize=None, painter=None, clusterColors={})


Example of a good and simple docstrings:
Code: Select all
In [33]: ?igraph.Graph.Read
Type:      instancemethod
Base Class:   <type 'instancemethod'>
String Form:   <bound method type.Read of <class 'igraph.Graph'>>
Namespace:   Interactive
File:      /home/offero/build/bdist.linux-x86_64/egg/igraph/__init__.py
Definition:   igraph.Graph.Read(klass, f, format=None, *args, **kwds)
Docstring:
    Unified reading function for graphs.
   
    This method tries to identify the format of the graph given in
    the first parameter and calls the corresponding reader method.
   
    The remaining arguments are passed to the reader method without
    any changes.
   
    @param f: the file containing the graph to be loaded
    @param format: the format of the file (if known in advance).
      C{None} means auto-detection. Possible values are: C{"ncol"}
      (NCOL format), C{"lgl"} (LGL format), C{"graphml"}, C{"graphmlz"}
      (GraphML and gzipped GraphML format), C{"gml"} (GML format),
      C{"net"}, C{"pajek"} (Pajek format), C{"dimacs"} (DIMACS format),
      C{"edgelist"}, C{"edges"} or C{"edge"} (edge list), C{"adjacency"}
      (adjacency matrix), C{"pickle"} (Python pickled format).
    @raises IOError: if the file format can't be identified and
      none was given.

In [27]: ?igraph.Edge
Type:      type
Base Class:   <type 'type'>
String Form:   <type 'igraph.Edge'>
Namespace:   Interactive
File:      /usr/lib/python2.5/site-packages/python_igraph-0.5.1-py2.5-linux-x86_64.egg/igraph/__init__.py
Docstring:
    Class representing a single edge in a graph.
   
    The edge is referenced by its index, so if the underlying graph
    changes, the semantics of the edge object might change as well
    (if the edge indices are altered in the original graph).
   
    The attributes of the edge can be accessed by using the edge
    as a hash:
   
      >>> e["weight"] = 2
      >>> print e["weight"]
      2


You could probably get good community contributions here too. I would gladly help where I could.

Return to Wish List