[cctbxbb] Sphinx docs for CCTBX

Richard Gildea rgildea at gmail.com
Fri Aug 15 10:30:28 PDT 2014


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 at 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 at 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 at phenix-online.org
>> http://phenix-online.org/mailman/listinfo/cctbxbb
>>
>>
>
>
> --
> Dr. Oliver B. Zeldin
> Brunger Group
> Stanford University
>
> _______________________________________________
> cctbxbb mailing list
> cctbxbb at phenix-online.org
> http://phenix-online.org/mailman/listinfo/cctbxbb
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20140815/a2d25735/attachment.htm>


More information about the cctbxbb mailing list