Re: [cctbxbb] Sphinx docs for CCTBX

Would the sphinx docs generated via doxygen be exactly what we would want for the Python interface? Would they be able to differentiate which parts of the C++ interface are exposed to Python and which are not? It isn't clear to me that documentation of the C++ interface is necessarily the same as documentation of the Python interface. To a user of the Python interface, it should ideally be transparent as to whether a given class/function is a pure Python implementation or a Boost.Python extension. Of Nat's suggestions I prefer number 2 as the simplest. I don't like the idea of having to write the documentation into the Boost.Python binding. On 15 August 2014 18:12, Oliver Zeldin wrote:

this:

https://github.com/michaeljones/breathe/tree/master

Is referenced in the sphinx FAQ, and seems pretty stable. Thoughts?

Oli

On Fri, Aug 15, 2014 at 9:56 AM, Luc Bourhis wrote:

...

Hi guys,

my 2p about that if you don't mind.

I think that ideally, we should try to find a way to pass the doxygen documentation into Sphinx.

If it is too much work to figure out, then of your 3 variants, (3) would be my preferred choice because it puts the documentation as close to the code that is actually documented, i.e. the wrapped C++ code. If the code has already been structured as your (1), this is most likely because the Python function does more than the C++ function, and the documentation should be in the overriden Python function then. Your variant (2) is just too ugly to my taste.

Best wishes,

Luc

_______________________________________________ cctbxbb mailing list [email protected] http://phenix-online.org/mailman/listinfo/cctbxbb

-- Dr. Oliver B. Zeldin Brunger Group Stanford University

_______________________________________________ cctbxbb mailing list [email protected] http://phenix-online.org/mailman/listinfo/cctbxbb