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
extension for sphinx which documents archetypes schema automaticaly
.. collective.sphinx.autoatschema:: my.packages.content.mycontent.MySchema
another extension for sphinx which includes doctest from also other packages.
.. includedoc:: my.package:/relative-to-package/path/README.txt
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.
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.
join us at http://www.openplans.org/projects/plonedevdocs where we brainstorm about possible options.