The future of TurboGears documentation

[Mark Ramm]

I'd like to start a conversation about the future of TurboGears
documentation issues, and to start planning for the 1.1 and 2.0
releases.

1.1 will be reliatively easy -- we'll be able to port a lot of our
existing docs across to 1.1 as is. Docs which talk about templates,
should be converted to Genshi, and docs that talk about Kid should be
converted to SQLAlchemy.

The biggest projects will be to move the 20 min wiki tutorial over to
the new tools, and to go through all of the widget docs and make sure
that we are using the ET() wrapper around widget render calls.

Do you think it would make sense to have a tg 1.1 doc sprint sometime
in mid July?

As for TurboGears 2.0. Right now I'm focusing on creating good
developer docs, good docstrings, and good in-code comments. I want
it to be a lot easier to understand, and I want us to be able to
quickly and easily generate API docs from the code.

--
Mark Ramm-Christensen
email: mark at compoundthinking dot com
blog: www.compoundthinking.com/blog

[gas...@gmail.com]

> email: mark at compoundthinking dot com
> blog:www.compoundthinking.com/blog

I was working on an SQLAlchemy doc-style all-in-one tutorial based
upon 1.0 docs and clean the download&install section a bit.
http://docs.turbogears.org/1.1/RoughDocs/Tutorial

Fortunately its based upon genshi and SQLAlchemy by default, and the
doc haven't migrated to cp3 yet :P

I think to make an SQLAlchemy doc-style tutorial, which cover major
dev methods/functions and links to the references, might bring more
motivation than just migrate docs from 1.0.

[Mark Ramm]

> I was working on an SQLAlchemy doc-style all-in-one tutorial based
> upon 1.0 docs and clean the download&install section a bit.
> http://docs.turbogears.org/1.1/RoughDocs/Tutorial
>
> Fortunately its based upon genshi and SQLAlchemy by default, and the
> doc haven't migrated to cp3 yet :P
>
> I think to make an SQLAlchemy doc-style tutorial, which cover major
> dev methods/functions and links to the references, might bring more
> motivation than just migrate docs from 1.0.

This sounds like a fantastic tutorial, and it would be a great
contribution to the 1.1 documentaiton efforts.

I do still think we need to do some doc migration/updates in the wiki.
But we'll do what we can.

[Paul Johnston]

Hi

1.1 will be reliatively easy -- we'll be able to port a lot of our
existing docs across to 1.1 as is.  Docs which talk about templates,
should be converted to Genshi, and docs that talk about Kid should be
converted to SQLAlchemy.

I agree, it's not a massive change. And I'm game for a sprint in July.

I think the main decision is how we recommend using SQLAlchemy. I reckon most TG users will want to use the Active Record pattern, as it's simpler than the Data Mapper pattern. Should we embrace Elixir as the recommended way to use SA with TG? I have to admit I've still not touched Elixir, I have found ActiveMapper to be adequate for my needs.

Paul

[gas...@gmail.com]

> Should we embrace Elixir as the recommended
> way to use SA with TG? I have to admit I've still not touched Elixir, I have
> found ActiveMapper to be adequate for my needs.
>
> Paul

I've made a patch for Elixir template
http://trac.turbogears.org/ticket/1402

maybe somebody could give it a try and see if it's suit for 1.1 or 2.0
version

--
Fred

[Jorge Vargas]

I remember we had several goings back and forth with the first package
by Jonathan, can't recall it's name but it was pre-elixir we had the
problem that people where expecting SA and found *that* and then we
had the other problem that the layer wasn't exactly "completed" I say
we stick with "plain SA" and have specialiced docs for the "other
layers", kind of what we'll have for genshi and other templates.
>
> Paul
>
> >
>

[Mark Ramm]

I'd suggest moving discussion of weather 1.1/2.0 should use elixir by
default to the trunk mailing list.

Hi

Paul

[Paul Johnston]

Hi,

In terms of TurboGears code, I think TG should be setup for fairly plain
SA; although you'll have to use SessionContext to get the automatic
transactions. Anything on top of this - Elixir, assign_mapper, etc.
should "just work".

But in therms of the documentation, I think we should recommend an
active record pattern, at least in the basic tutorials. The reason being
is that newcomers will find the data mapper pattern too complicated -
certainly if I was a newbie and I compared plain SA to Django I'd say
that plain SA was needlessly complicated. Elixir should stack up ok.

Paul

Mark Ramm wrote:

>I'd suggest moving discussion of weather 1.1/2.0 should use elixir by
>default to the trunk mailing list.
>
>