Hi Luc,<div><br></div><div>I found one here after some random browsing: <a href="http://cctbx.sourceforge.net/current/python/rstbx.viewer.html">http://cctbx.sourceforge.net/current/python/rstbx.viewer.html</a>, i.e.</div><div>
<br></div><div><dt style="font-family:'Times New Roman';font-size:medium;background-color:rgb(240,240,248)"><a name="image-get_intensities_in_box"><strong>get_intensities_in_box</strong></a>(self, x, y, boxsize<font color="#909090">=400</font>, mag<font color="#909090">=16</font>)</dt>
<dd style="font-family:'Times New Roman';font-size:medium;background-color:rgb(240,240,248)"><tt># XXX does this need to be in C++?</tt></dd><div><br></div><div>which looks to me like it comes from rstbx/viewer/__init__.py. But it may just be that the code has changed since the last documentation run.</div>
<div><br></div><div>I don't suppose this is a problem, I'm just trying to understand what the rules are when the code is scraped for docs.</div><div><br></div><div>Cheers</div>-- David<br>
<br><br><div class="gmail_quote">On 8 October 2012 16:01, Luc Bourhis <span dir="ltr"><<a href="mailto:luc_j_bourhis@mac.com" target="_blank">luc_j_bourhis@mac.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word">Hi David,<br><div><div class="im"><br><blockquote type="cite"><div>I've got a few questions about the automatically generated Python documentation.</div><div><br></div><div>1. Is this done by doxygen like the C++ documentation?</div>
</blockquote><div><br></div></div><div>No. It has traditionally been generated with pydoc. A few years back, Jan Marten Simons added generation with sphinx, which gives much better looking html pages.</div><div class="im">
<br><blockquote type="cite"><div>2. What are the rules that determine whether text in source files is included as documentation or not? Clearly docstrings are, but also some comments do (only those at module scope?)</div>
</blockquote><div><br></div></div><div>As far as I know, only docstrings should be gathered by pydoc or sphinx. Could you give me an example of those other comments?</div><div class="im"><br><blockquote type="cit!
e">
<div>3. Similarly, what determines which packages are documented or not? For example, from <a href="http://cctbx.sourceforge.net/current/python/rstbx.html" target="_blank">http://cctbx.sourceforge.net/current/python/rstbx.html</a>, cftbx is documented but bpcx is not. Is there at some point a manual decision about what should be documented?</div>
</blockquote><br></div></div><div>No. Some developers like to put quite a bit of comments, other don't bother. It also depends on how much in a hurry the developer is of course as documentation does nothing to help reaching a dead line.</div>
<div><br></div><div>Best wishes,</div><div><br></div><div>Luc</div><div><br></div></div>
<br>_______________________________________________<br>
cctbxbb mailing list<br>
<a href="mailto:cctbxbb@phenix-online.org">cctbxbb@phenix-online.org</a><br>
<a href="http://phenix-online.org/mailman/listinfo/cctbxbb" target="_blank">http://phenix-online.org/mailman/listinfo/cctbxbb</a><br>
<br></blockquote></div><br></div>