Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Ticket #2354 (closed documentation: migrated)

Opened 10 years ago

Last modified 8 years ago

Collection of documentation suggestions

Reported by: kvdb Owned by: pedersen
Priority: normal Milestone: 2.1 docs
Component: TurboGears Version: 2.1
Severity: normal Keywords:


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 <html><body>... 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:

<div xmlns:py="http://genshi.edgewall.org/"> this is all that is required to load me. </div>

Change History

comment:1 Changed 10 years ago 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.

comment:2 Changed 10 years ago 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.

comment:3 Changed 10 years ago by chrisz

It would be nice to have a recipe for handling concurrent editing (see  here).

comment:4 Changed 10 years ago 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?

comment:5 Changed 10 years ago 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.

comment:6 Changed 10 years ago 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.

comment:7 Changed 10 years ago 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.

comment:8 Changed 10 years ago by percious

  • Milestone changed from 2.1 to 2.1 docs

comment:9 Changed 8 years ago by pedersen

  • Status changed from assigned to closed
  • Resolution set to migrated
Note: See TracTickets for help on using tickets.