Documentation Notes and Updates

[Michael Pedersen]

I've begun working with Laurin Killian heavily on these updates, and
they are starting to show some fruit. The initial checkout of the
current tg2.1 mercurial repository showed over 200 warnings on a new
"make html". We have that down to 0 now.

We've also made a fairly long list of "todo" items, using the Sphinx
todolist extension. And, on top of all that, we've started to make
some dents in that list.

All in all, I think the results are starting to show for themselves.

http://web.icelus.tzo.com/~marvin/tg2 <-- the new docs
http://turbogears.org/2.0/docs/index.html <-- current docs

Any/all feedback is welcomed. If you've already sent in notes, they
haven't been missed. I've got several more threads marked as "add
these to docs too", but haven't gotten around to doing so. Been a bit
busy getting the docs to this point :)

The new docs link above will be automatically updated every night,
whether or not I get updated docs uploaded to bitbucket. So it can
always be used to check out the current progress of the updates.

Thank you.

[Diez B. Roggisch]

First of all - great work!

I took a peek into the validation examples, and two things are missing IMHO:

- a recipe to replace the old callable-argument-mechanism known in TG1 to
dynamically decide which form (or other validator set) to use.

- how to work with validation inside the controller - actually, raising
formencode.Invalid should work, and a small bit about how to do that with
actually providing meaningful error messages.

Did you publish the HG-repository? I could try & enhance the docs myself then.

Diez

[Diez B. Roggisch]

> I took a peek into the validation examples, and two things are missing
> IMHO:

And another remark: while I like the exhaustive list of validators, it would
be cool if it could

- take up a bit less space, or be moved to a separate page. Dunno if there is
any fancyness sphinx could be teached to do.
- the entries could link to the class-docs

Diez

[Michael Pedersen]

On Mon, Jul 20, 2009 at 8:12 AM, Diez B. Roggisch <de...@web.de> wrote:

Did you publish the HG-repository? I could try & enhance the docs myself then.

I knew I forgot something when I sent this out. The HG repository is available at https://bitbucket.org/pedersen/tg_2_1_docs/ .

I've also attached this thread to my TG docs notes folder. Once I get through most of the other todo list items, I'll be going through that folder and adding those in as well. Lots of work to go, but it's manageable at least.

--
Michael J. Pedersen
My IM IDs: Jabber/pede...@icelus.tzo.com, ICQ/103345809, AIM/pedermj022171
         Yahoo/pedermj2002, MSN/pederm...@hotmail.com

[spam&eggs]

Diez,

Great to hear you might be into enhancing the docs yourself!

Here is our current information about downloading, and building the
docs in order
to contribute most easily to the effort:

http://web.icelus.tzo.com/~marvin/tg2/building_docs.html

Even this document needs work, and if you do end up helping, we want
to find
ways to make it more clear on how to contribute to the effort.

Obviously, not everyone will go through the effort of building the
docs, and
comments via disqus are still appreciated. We're trying to find
ways to make
the docs more complete, and well, more helpful.

-Laurin
... still doesn't know how he got quite so involved in this.
I suppose helping write docs is one way to really learn...

[Seth]

Michael & Laurin,

Good on ya!

I'm currently writing a medium-sized project with TG2, and am doing
various posts to my blog as I come up with different "issues" that
need a simple howto/tutorial. Is there somewhere that I can submit
these as I write them up? I've never touched Sphinx/RST so I doubt
I'll be doing any "Sphinxing" of my own.

Thanks,
Seth

[spam&eggs]

Seth,

We appreciate any help we can get including new tutorials.
If we can't get them in RST format, plain text is the next best
thing. RST isn't actually too far from plain text anyway.

We are especially interested in reviewing the current docs, and
finding out things that are missing. One way I see of dealing
with missing parts is to link to topics covered elsewhere.

So, you can help us with tutorials by at least sending us a link to
a tutorial if you create one, and the tutorial in plain text to
save us that translation anyway.

I hope to talk with you more later about this here or in IRC, but
right
now I have to run.

-Laurin

[Kevin Horn]

One thing that might be helpful to new users is a breakdown of the file/directory structure of a quickstarted project.  Its not always obvious to those new to TG what all those files actually do, and which ones are expected to be edited by developers.

Kevin Horn

[percious]

There is a detailed breakdown here:
http://turbogears.org/2.0/docs/main/QuickStart.html#explore-the-rest-of-the-quickstarted-project-code

cheers.
-chris

On Jul 21, 10:18 am, Kevin Horn <kevin.h...@gmail.com> wrote:
> One thing that might be helpful to new users is a breakdown of the
> file/directory structure of a quickstarted project.  Its not always obvious
> to those new to TG what all those files actually do, and which ones are
> expected to be edited by developers.
>
> Kevin Horn
>

> On Mon, Jul 20, 2009 at 11:51 AM, spam&eggs <t...@streamlined-dev.com>wrote:
>
>
>
>
>
> > Diez,
>
> > Great to hear you might be into enhancing the docs yourself!
>
> > Here is our current information about downloading, and building the
> > docs in order
> > to contribute most easily to the effort:
>

> >http://web.icelus.tzo.com/~marvin/tg2/building_docs.html<http://web.icelus.tzo.com/%7Emarvin/tg2/building_docs.html>

>
> > Even this document needs work, and if you do end up helping, we want
> > to find
> > ways to make it more clear on how to contribute to the effort.
>
> > Obviously, not everyone will go through the effort of building the
> > docs, and
> > comments via disqus are still appreciated.    We're trying to find
> > ways to make
> > the docs more complete, and well, more helpful.
>
> > -Laurin
> > ...  still doesn't know how he got quite so involved in this.
> > I suppose helping write docs is one way to really learn...
>
> > On Jul 20, 8:12 am, "Diez B. Roggisch" <de...@web.de> wrote:
> > > On Monday 20 July 2009 06:59:39 Michael Pedersen wrote:
>
> > > > I've begun working with Laurin Killian heavily on these updates, and
> > > > they are starting to show some fruit. The initial checkout of the
> > > > current tg2.1 mercurial repository showed over 200 warnings on a new
> > > > "make html". We have that down to 0 now.
>
> > > > We've also made a fairly long list of "todo" items, using the Sphinx
> > > > todolist extension. And, on top of all that, we've started to make
> > > > some dents in that list.
>
> > > > All in all, I think the results are starting to show for themselves.
>

> > > >http://web.icelus.tzo.com/~marvin/tg2<http://web.icelus.tzo.com/%7Emarvin/tg2><--

[spam&eggs]

Kevin (and Percious/Chris),

I was thinking about expanding from that diagram - giving a little
more detailed explanation of what you get out of the box with a
quickstart.

What I was thinking might be a good idea is to expand upon mramm/
percious's tutorial at pycon:

http://bitbucket.org/mramm/pycon-tg-tutorial/

particularly the pages: quickstart, looking_around and genshi/
sqlalchemy "in_10".

Obviously, I should probably ask mramm if this is cool to do...
percious, is it OK with you?


Here is the "built" version of the quickstart page - sort of, I'm not
sure how to just display it:

http://bitbucket.org/mramm/pycon-tg-tutorial/src/tip/docs/_build/html/quickstart.html


I probably won't get this done right away - I'm still (slowly) going
through some updates to other tutorials from the docs. It's
surprising how long it can take...

Ideally, what I'd like to do, is show briefly what turbogears gives
you with a quickstart above and beyond a pylons quickstart. Probably
linking a bit to the pylons book for additional background.

-Laurin

ps: I'm not sure why I still show up as "spam&eggs" - it was a goofy
monty python reference I used a long time back when I was trying to be
more anonymous...

On Jul 21, 3:43 pm, percious <ch...@percious.com> wrote:
> There is a detailed breakdown here:http://turbogears.org/2.0/docs/main/QuickStart.html#explore-the-rest-...