one week of riding sphinx

i made 3 releases today to pypi:

• SphinxBuilder
  buildout recipe for sphinx. that way writing/deploying sphinx docs becomes easier. initialy code was written by tarek i brought it from 0.1.2 to 0.2
  
  
• AutoATSchema
  extension for sphinx which documents archetypes schema automaticaly
  example:
  .. collective.sphinx.autoatschema:: my.packages.content.mycontent.MySchema
  
  
• IncludeDoc
  another extension for sphinx which includes doctest from also other packages.
  example usage:
  .. includedoc:: my.package:/relative-to-package/path/README.txt
  

inititaly i start looking into sphinx to see if also plone can also benifit from this usefull tool. i'm still doing research and will shortly publish my results and my ideas how to use sphinx in plone process.

i must mention that work on SphinxBuilder and AutoATSchema was sponsored by Headnet. thank you Headnet.

where to go from here?
you can see work in progress for possible replacement of api.plone.org. well its only research so currently only tree packages are there: plone.contentrules, Products.Archetypes, Products.ATContentTypes. there are a lot of stuff missing consider it as staring point.
http://docs.garbas.si/plone-latest

why i think sphinx is the right tool for api.plone.org?

• definitly *not* because sphinx is new hot stuff, but because of its features and because it makes can integrates well in plone proccess
  
• very few ppl uses api.plone.org because of its current state. plone was by some extend ment to be framework and frameworks needs good, clear api so new developers can "plug-n-play"
  
• we all know that api is not the strongest point of plone. well i could criticise it, but that wont change anything. with sphinx we can hide bad api parts or emphasise good / useful ones.
• best / up-to-date documentation can only be written by core developers at the time of development (and maybe reviewed by doc team). well maybe not only but is sure the easiest way for all. we all are aware of TDD, there is several very well writen doc(test)s, but hidden from eayes of public.
  
• because i think this can be the stongest feature for plone4. yes, having up-to-date documentation can do magic or at least attract more developers.
  

wanna help?
join us at http://www.openplans.org/projects/plonedevdocs where we brainstorm about possible options.