Clean docstrings

[julien]

Hi Chris, 

I am trying to use docstrings in the Nautilus.py module so that it is clear what the public interface is. I have used standard conventions to hide some functions as private. However the output isn't exactly what I want because a number of Sire methods end up exposed. Is there a simple workaround or should I give up on having help(Nautilus) return only the 'public' interface ?

In the example below, the only function that should have been listed in FUNCTIONS is cell2grid()

julien@ubuntu:~/sire.app/test$ ~/sire.app/bin/python 

"/home/julien/sire.app/share/Sire/scripts/python.py" 

Starting /home/julien/sire.app/bin/python: number of threads equals 1

WARNING: IPython History requires SQLite, your history will not be saved

Python 3.3.3 (default, Aug 13 2014, 21:53:23) 

Type "copyright", "credits" or "license" for more information.

IPython 2.2.0 -- An enhanced Interactive Python.

?         -> Introduction and overview of IPython's features.

%quickref -> Quick reference.

help      -> Python's own help system.

object?   -> Details about 'object', use 'object??' for extra details.

In [1]: from Sire.Tools import Nautilus

In [2]: help(Nautilus)

Help on module Sire.Tools.Nautilus in Sire.Tools:

NAME

    Sire.Tools.Nautilus

DESCRIPTION

    Nautilus is a python module that implements the grid cell theory (GCT) method. 

    GCT enables analysis of explicit solvent molecular dynamics simulations to compute and spatially resolve enthalpies and entropies of 

    water molecules

    

    Details of the methodology are available in the following publications:

    

    Evaluation of Host/Guest Binding Thermodynamics of Model Cavities with Grid Cell Theory

    Michel, J. ; Henchman, R.H. ; Gerogiokas, G. ; Southey, M. W. Y. ; Mazanetz, M. P. ; Law, R. J. ; 

    J. Chem. Theory Comput., 10 (9), 2014, 4055-4068

    

    Prediction of Small Molecule Hydration Thermodynamics with Grid Cell Theory

    Gerogiokas, G. ; Calabro, G. ; Henchman, R.H. ; Southey, M. W. Y. ; Law, R. J. ; Michel, J. 

    J. Chem. Theory Comput., 10 (1), 35 - 48, 2014

    

    .

FUNCTIONS

    Gamma(...)

        Gamma( (object)alpha [, (object)x]) -> float :

        

            C++ signature :

                double Gamma(double [,double])

    

    acute(...)

        acute( (object)angle) -> object :

        

            C++ signature :

                SireUnits::Dimension::PhysUnit<0, 0, 0, 0, 0, 0, 1> acute(SireUnits::Dimension::PhysUnit<0, 0, 0, 0, 0, 0, 1>)

    

    align(...)

        align( (object)p, (object)q [, (bool)fit=True]) -> object :

        

            C++ signature :

                QVector<SireMaths::Vector> align(QVector<SireMaths::Vector>,QVector<SireMaths::Vector> [,bool=True])

    

    boys(...)

        boys( (int)m, (object)x) -> float :

(....)

    

    cell2grid()

        cell2grid averages the contents of a collection of cell files and output a set of grid files in 

        dx and pdb format that spatially resolve thermodynamic components of the excess free energy of water 

        molecules.

    convert(...)

        convert( (object)val, (Unit)to_units) -> float :

        

            C++ signature :

                double convert(double,SireUnits::Dimension::Unit)

        

        convert( (object)val, (TempBase)to_units) -> float :

        

            C++ signature :

                double convert(double,SireUnits::Dimension::TempBase)

        

        convert( (object)val, (Unit)from_units, (Unit)to_units) -> float :

        

            C++ signature :

                double convert(double,SireUnits::Dimension::Unit,SireUnits::Dimension::Unit)

[Christopher Woods]

Hi Julien,

No, I am sorry that you can't hide all of these functions. These are
functions from Sire.Maths etc. that have been imported into the
Nautilus namespace. I think that the only chance would be to remove
any "from Sire.Maths import *" calls in the Nautilus module and to
instead use "import Sire.Maths as SM" and add "SM." in front of any
Sire.Maths function calls.

I have to say that I found getting the docstrings out of C++ and into
Python (and for Python to show useful, rather than overly complex
docstrings) to be such a pain that I gave up and just now put the
doxygen output up on the website (it is always synced to the current
release and is updated every time I update trunk).

Cheers,

Christopher

> --
> You received this message because you are subscribed to the Google Groups
> "Sire Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sire-develope...@googlegroups.com.
> To post to this group, send email to sire-de...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sire-developers.
> For more options, visit https://groups.google.com/d/optout.



--
---------------------------------------------------------
Christopher Woods
+44 (0) 7786 264562
http://chryswoods.com