On Jan 27, 2009, at 7:17 PM, Istvan Albert wrote:
>> In our next developer conference call, we should probably discuss how >> your site should change our current approach(es) to documentation, >> which at present are scattered all over the map. > > Yes, I plan to port all the documentation and scattered tidbits over > to this format. Everything is/will be in the main repository tracked > via git. Besides html one can format these docs as latex/pdf or plain > text. Could this easily incorporate our existing documentation, which is in latex format? (I just followed the same system for docs that Python uses; I just took the Python docs templates and replaced it with my content. The HTML is then generated by latex2html again using the Python team's templates, scripts etc. All of that is in the pygr git repository, in the doc subdirectory, if you want to look at it in detail). > > > And a reminder (that never ceases to amaze me) most of the code > samples are actually executed and verified that they produce the > presented outcome. There is a hidden section in each doc that allows > us to do some scaffolding for code snippets that need some > initialization - without complicating the main documentation. very cool > > > One outstanding issue is how to format the pygr API that is > automatically extracted from the sources: > > http://atlas.bx.psu.edu/pygr/epydoc/index.html > > We can use Sphinx for that as well, but over the years I have grown > fond of epydoc. It directly generates javadoc like files from the > code with no other step involved, I really like the frame based > navigation here, usually frames suck but in this case allows one to > jump to various documentation sections with ease. based on my first quick perusal, this looks useful. In the past I've found auto-generated doc systems to be too ugly to use, e.g. the generated docs get bloated with inherited methods that have little to do with that specific class, etc. This looks better. One obvious benefit: it would immediately make us improve many of our docstrings... ;-) You could argue that unless you put in place such a system, there's a tendency to not update or refine the docstrings as much as you should, because you have the feeling that no one's reading them. -- Chris --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "pygr-dev" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/pygr-dev?hl=en -~----------~----~----~----~------~----~------~--~---
