Collection of documentation suggestions

[pedersen]

This issue existed in Trac. The original can be viewed at http://trac.turbogears.org/ticket/2354

This issue existed on SourceForge. The original can be viewed at https://sourceforge.net/p/turbogears2/tickets/24

[pedersen]

Original Author: pedersen, Original Timestamp: 2011-03-27 20:40:35.156000

Original Body: As discussed with percious on IRC, I'll post anything that took me a long time to figure out, and that I think is missing from the documentation. Note that I don't criticize the docs, just trying to improve them a little. Tell me if this is helpful and if I should continue adding things to this ticket.

Topic "Scheme migration". I was expecting to find out how to update my current database with any new tables/changes that I defined in my model. In TG1, I had tg-admin sql status/create. Where has that gone?

Topic "TGControllers" I tried implementing the lookup chain. Like the document suggests, but one level deeper. Only the end of the chain may be of type object, all others in the chain need to derive from BaseController?, or any used tg.url()'s in the templates won't get updated. Maybe a link to a unittest testing a deeper chain?

Topic "http://turbogears.org/2.0/docs/main/ToscaWidgets/Cookbook/AutoComplete.html" After selecting an 'ingredient' from a tw.jquery.autocomplete input element that I defined with a form as explained in the mentioned tutorial I want to perform another jquery action. I want to get a piece of html containing all recipes with that ingredient. I already exposed the HTML. I just need to define the action. I did this with a custom jquery ajax() call. Guess there is better way.

More on jquery. Is there a widget that I can put in a form that just loads html from an exposed method? Anyway, the HTML that gets pulled in through an ajax() jquery call from my last example is put into the DOM and doesn't need the full ... headers tags. I never came across this simple observation in the documentation. Noting this might be useful. This is the template format that might be used:

this is all that is required to load me.

---

08/28/09 13:59:45 changed by pedersen

owner set to pedersen.
status changed from new to assigned.

Absolutely this is useful. Please continue to attach notes here. I'm taking this ticket, and attaching it to me, so that I can keep up to date on it.
Delete 09/01/09 07:34:49 changed by kvdb

Topic "http://turbogears.org/2.0/docs/main/Config.html#configuration-in-the-ini-files"

Missing how to set XHTML1.1 as output instead of the default XHTML 1.0 transitional. Was commented out in TG1, so it was easy to find and change. Not sure how to do it now. Using the default Genshi in my case.
Delete 09/20/09 02:08:02 changed by chrisz

It would be nice to have a recipe for handling concurrent editing (see here).
Delete 09/22/09 06:14:58 changed by kvdb

I was looking for a way to validate and process one or multiple similar named parameters, as seen in the example with the directors parameter: http://turbogears.org/2.0/docs/main/RestControllers.html?highlight=restcontroller#updating-our-record-in-the-database-with-validation

May be nice to explain how the directors parameter can enter the system. One director as directors=1 and multiple directors as directors=1&directors=2 What's missing is the validation of this parameter. Is that at all possible using the default validators?
Delete 09/22/09 06:18:44 changed by kvdb

I was wondering if the examples found in the documentation are (or should be) also available as runnable code-snippets. Would it be possible to include these in the unittests for TG? (as doctest maybe). That would help keeping them up-to-date and bug-free.
Delete 09/28/09 12:16:02 changed by chrisz

We should document why/when to use tmpl_context vs. passing data in the dict as return value (basically, use the former for widgets and the latter for data). This is often confusing for new TG2 users. We should also make sure this is done consistently in all of the examples in the docs.
Delete 10/01/09 01:24:16 changed by cdevienne

Another subject that is absent from the TG 2.0 documentation is TurboJson?.

If one wants to define custom json format for its own types, only the TG1 documentation mention how to do it.

Note that because of #2212, only a 2.0.x version may be concerned.
Delete 10/01/09 13:01:11 changed by percious

milestone changed from 2.1 to 2.1 docs.

[pedersen]

Original Author: pedersen, Original Timestamp: 2012-08-24 01:39:37.511000

Original Body: - version: 2.1.0 --> 2.1.5

• milestone: 2.2.0 --> 2.3.0