[BlueBream] apidoc ? onlinehelp ? preference ?

[Ilshad Khabibullin]

2010/4/24 Christophe Combelles <ccomb at free.fr>

> 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.
>

I mean both, yes, I.e. at least 2 - development and production. Which
difference usual? In my practice, bootstrap user, includes to mail
configurations (or just mailer directive directly in size.zcml) - at least
in each project. Like to see more experience from other developers to make
resolution.


> 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.
>
>
Difficult to find a balance - so let's define the goals.



> >
> >
> >
> >     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
>
> _______________________________________________
> bluebream mailing list
> bluebream at zope.org
> https://mail.zope.org/mailman/listinfo/bluebream
>



-- 
Ilshad R. Khabibullin
http://astoon.zwiki.org
+7 922 600 56 06
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.zope.org/pipermail/bluebream/attachments/20100424/95f95ee8/attachment.html