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 <zeldin@stanford.edu> 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 <luc_j_bourhis@mac.com> 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
cctbxbb@phenix-online.org
http://phenix-online.org/mailman/listinfo/cctbxbb




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

_______________________________________________
cctbxbb mailing list
cctbxbb@phenix-online.org
http://phenix-online.org/mailman/listinfo/cctbxbb