[BlueBream] apidoc ? onlinehelp ? preference ?

[Christophe Combelles]

Ilshad Khabibullin a écrit :
> Hi Christophe,
> 
> 2010/4/23 Christophe Combelles <ccomb at free.fr <mailto:ccomb at free.fr>>
> 
>     hi,
> 
>     what about bringing back zope.app.apidoc ? It is a very useful tool
>     during
>     development and it allows to dynamically add other namespaces such
>     as z3c, zc,
>     and even the project packages. There is probably a few changes to do
>     in apidoc
>     registrations. A very good thing would then be to move it to
>     zope.apidoc later.
> 
>  
> We need this, it is powerfull tool, and developer can include apidoc in 
> any moment. But I think, developer needs these features mostly in 
> _some_context_, i.e. to inspect components "on fly", not just to see 
> docs. The more so the documentation should be moved out the doctests in 
> future, yes? In this case displaying them via wsgi-server is not the 
> best idea... there are editors, Sphinx, etc. Summary, lets' divide:
> 
> 1) Need to see dynamic data - i.e. components, relations between them.
> 2) Need to see static documentation.
> 
> For dynamic data - inspect registry. Sometimes, we dive into exist zope3 
> project and "I am feeling that somewhere registered adapter, but where 
> he, is the devil...".


I agree we need both static doc and dynamic doc.

Because when the app can't start, there is no apidoc...  The 
http://apidoc.zope.org already is a static doc. Is there a way to include the 
static generation tool in a project?


> 
>     There is a way to enable it only in devmode with
>     zcml:condition="have devmode".
>     I think we can provide at least two buildout files for this purpose,
>     one for
>     production, one for development using devmode and apidoc.  It can be
>     easily done
>     with the templating system currently included.
> 
> 
> BlueBream is server-side software. When I create project, I need deploy 
> this project on my sandbox and on server, in any case. So, I spend time 
> for production-server-boilerplates, copy-past from older projects :)
> 
> Then we need decide:
> 1) We provide the simple and policy-free template
> 2) Or we provide powerful template for server-side projects. It can be 
> relatively polcy-free, I think.


I don't know what is the best. We need to ease both development and production, 
but we must not bring too much complexity, nor large configuration files.
So that beginners shouldn't be frightened.  It *must* remain easy to understand 
and easy to explain.
We should probably do some tests in sandbox branches.


> 
>      
> 
>     If there is a way to do this without needing the templating, I would
>     be +1 to
>     remove the templating.
> 
>  
> alternative - zcml in .cfg files - here is example: 
> http://paste.lisp.org/+23S0
> 
> But it seems, templates is better... I'm not sure exact... Personally 
> for me, these big and mess buildout.cfg files is bad. And system 
> administrators not liked this, I know (because we need provide 
> instructions how to edit these files, remove or add bootstrap manager 
> and etc.)

I'm also *strongly* against including ZCML (and zope.conf) in the buildout. It 
make me think of the desperately giant plone buildouts I regularly see. It's 
unreadable, and most people are confused.


> 
> 
>     Same question for zope.app.onlinehelp and zope.app.preference ?
>     _______________________________________________
>     bluebream mailing list
>     bluebream at zope.org <mailto:bluebream at zope.org>
>     https://mail.zope.org/mailman/listinfo/bluebream
> 
> 
> 
> 
> -- 
> Ilshad R. Khabibullin
> http://astoon.zwiki.org
> +7 922 600 56 06