On Sun, Jan 4, 2009 at 9:04 PM, akean <[email protected]> wrote: > > > Wiki documentation: > > Have just started working through your tg2 tutorials, > and decided to send some feedback - > just want to say up front that for a first impression, the wiki20 > tutorial is very nicely done and really clear - thanks!- > > I downloaded the docs is rst, so I'll refer to them: > A) wiki20 tutorial: main/Wiki-20/wiki20.rst > > and > B) toscawdigets tutorial: main/ToscaWidgets/forms.rst > > I'll inculde the header for the current section in each of the items > - > in case it helps. > > > Preface - the hardest part of doing these tutorials (when everything > is running smoothly) is spotting what has to be changed when a > new (or new version of an existing) page is presented - sphinx > doesn't seem to have a generic highlighter for "new code" within a > code-block. > That would make a huge difference! > So the majority of time is spent going through the current version > against the tutorial line by line to see what has changed. > (Yes I could copy and paste, but then I'd have no idea what's going > on.) > > So most of my errors were because of my typos. > But occasionally it's comforting to know you're making some > progress - e.g. by making changes to the database. > So I've inserted and "extra info would be nice" item, db-specific. > > *************** > A. wiki20.rst > *************** > > 1) typo -- missing "with": > > >> 23 Setup >> 24 ================== > .. >> 54 #. A database. Python 2.5 comes _with_ <<<--- >> 55 **sqlite**, so if you have Python 2.5, don't do anything. If you're > > > 2) pitfall and omission > > You should perhaps warn that the documentation is > in sync with the tutorial, so to make sure people use the same names > your > tutorials uses, or expect loud sphinx errors in your docs. > > e.g. after following the helloworld intro, where an app > called Helloworld created a directory called Helloworld, > I was instructed to set up the Wiki20 tutorial to > type: > >> 82 Quickstart >> 83 ==================================== >>... >> 102 Enter project name: Wiki 20 > > I decided not to use "Wiki20" instead of "Wiki 20 (no spaces in > directory names), and paster created a directory Wiki-20 > (inserted hyphen) and put the stuff there - > the docs refered to files on my filesystem under that directory > (Wiki-20) - which on my system didn't exist, so I got big sphinx > error-box in my docs at line 248 - referring to a directory named > as in the tutorial. > >> 234 Wiki Model and Database >> 235 ============================================ > >> 248 .. code:: Wiki-20/wiki20/model/__init__.py > > Unfortunately this occurred at exactly the place where there is a line > missing in the docs, so I spent forever trying to reconfigure the > docs. > Only to find the line was missing anyway! > > The missing line: > >> 244 to the module. Add the following line >> 245 *at the end of the file*. It's very important that this line is at the >> 246 end because of some initialization ordering issues: > > > (here should be inserted the line > > .. code-block:: python > > page_mapper=mapper(Page, pages_table) > ) > > (and change the colon to a period (full stop). > > > 3) not clear > > first mention of genshi py: >> 210 Displaying the Page >> 211 --------------------------- >> ... >> >> 220 Genshi directives are usually found within ``div`` or ``span`` tags, and >> 221 begin with the ``py:`` namespace. Each one represents a python block of >> 222 code, but instead of ending with the outdent as in python, the end of >> 223 the tag represents the end of the block. Look through the ``index.html`` >> 224 file to see the Genshi directives. >> > The only occurrence of Genshi directives in the index.html file is in > the > <meta content> tag (not everyone knows enough html to know the details > of this line): > >><head> >> <meta content="text/html; charset=UTF-8" http-equiv="content-type" >> py:replace="''"/> > > - a little confusing to know what to make of (no sign of divs or > spans). > "Looking through" didn't help much to see what was going on. > Perhaps wait for a clearer opportunity to draw attention to "py:" or > say what's going on here. > > 4) typo > >> 307 Initializing the Tables >> 308 -------------------------------- >>... >> 321 where you're used to seeing ``Session.commit()`` we use >> ``transaction.commit`` this calls the transaction manager which helps us to >> support cross database transactions, as well as transactions in non >> relational databases, but ultimately in the case of SQLAlchemy it calls >> Session.commit() just like _you_ might if you were doing it directly. > > "you" missing (inserted between _ and _) > > 5) ambiguity > >> 338 Adding Controllers >> 339 ======================================= > ... >> Now we will change the template used to present the data, by changing the >> 360 `...@expose`` line:: > >> 362 @expose('wiki20.templates.page') > > There are two @expose lines initially in the root.py file - > @expose('wiki20.templates.index') > and > @expose('wiki20.templates.about') line. > you don't specify which one - you mean index, I gather > > 6) extra info would be nice > > You could show people how to see their devdata.db file - > but they need sqlite3 on their system to do so. > (I use debian linux (unstable), and the standard sqlite installed > on unstable is (as of late Dec, 2008) sqlite2.) > > e.g. the code > > ---------------------------------------------------------------------------- > > sqlite session: > > $ sqlite3 devdata.db > sqlite> .help (see what help is available) > sqlite> .show (see what current settings are) > sqlite> .tables (see what tables are in the database) > sqlite> .schema pages (see the SQL create scheme used for > the pages table) > sqlite> SELECT * FROM pages; (see everthing (*) in the pages table) > sqlite> UPDATE pages SET data='new data' WHERE id=3; > (change 'data' field of record 3 in > pages table) > sqlite> .quit (quit sqlite) > $ (back to shell) > > Notes: there are two types of commands: > 1) sqlite commands which all begin with "." > 2) SQL commands which don't begin with a . > - these *must* be terminated with a ";" > SQL keywords are usually shown in uppercase, but are case- > insensitive. > ---------------------------------------------------------------------------- > > might be a nice interlude and give people the feeling they're making > some progress, and of checking their database. > As it is, the whole thing is done blind. > > 7) extraneous > >> 402 feel free to comment out (or remove) the ``flash()`` call too, to >> 403 tidy the output up a bit. > > This is extraneous: flash isn't used in the file. > It's imported, but there was no call made to it to comment our or > remove. > > 8) >> 459 Editing pages >> 460 ============================================ > ... >> 468 cd wiki20/templates >> 469 cp page.html edit.html >> 468 cd ../.. <<<----- > > the "cd ../../" line shouldn't be there. > > 9) typo: the "it's" should be 'its": > >> 509 Saving our edits >> 510 ================ > ... >> 532 SQLALchemy also provides a ``DBSession.commit()`` method which flushes >> and commits any changes you've made in a trasaction. TurboGears 2 provides >> a flexible transaction management system that automates this process >> wrapping each web request in _it's_ own transaction and automatically >> rolling back that transaction if you get a python exception, or return an >> HTTP error code as your response. > > 10) extraneous > > 537 What about WikiWords? > 538 ============================================ > > The new version of root.py has a repeated line at line 26 > >> 20 @expose('wiki20.templates.page') >> 21 def default(self,pagename="FrontPage"): >> 22 try : >> 23 page=DBSession.query(Page).filter_by(pagename=pagename).one() >> 24 except InvalidRequestError: >> 25 raise redirect("notfound", pagename=pagename) >> 26 page=DBSession.query(Page).filter_by(pagename=pagename).one() >> <<--- >> 27 content=publish_parts(page.data,writer_name="html")["html_body"] >> 28 root=tg.url('/') >> 29 content=wikiwords.sub(r'<a href="%s\\1">\\1</a>' % root,content) >> 30 return dict(content=content, wikipage=page) >> 31 >> > > > 11) typo '5' should be 'one'? > >> 597 Hey, where's the page? >> 598 ============================================ > > ... >> 620 As for the ``notfound`` method, the first 5 lines of the method adds a >> row to >> 621 the page table. From there, the path is exactly the same it would be >> 622 for our ``edit`` method. > > There are only 4 lines in the notfound method, including its header. > >> 47 @expose("wiki20.templates.edit") >> 48 def notfound(self,pagename): >> 49 page=Page(pagename=pagename,data="") >> 50 DBSession.add(page) >> 51 return dict(wikipage=page) > > Perhaps you mean "the first line"? > > 12) typo "bolded" is not a word >> 629 Adding a page list >> 630 ============================================ >> 631 >> 645 >> ... >> 646 The bolded section represents the Genshi code of interest. You can guess >> that >> > There's no such word as "bolded" in English. Try "The section in > bold". > > ************************** > B. Toscawidgets tutorial > ************************** > > 13) typos in forms.rst: > > 116 The Controller > 117 -------------- > 118 > 119 To show your form on the screen, we need to add a new controller > method that looks like the following > 120 > 121 :: > 122 > 123 # we tell expose which template to use to display the form > 124 @expose("genshi:toscasample.templates.new_form") > 125 def new(self, **kw): > 126 """Form to add new record""" > 127 import pylons > 128 # Passing the form in the return dict is no longer > kosher, you can- > 129 # set pylons.c.form instead and use c.form in your > template > 130 # (remember to 'import pylons' too) > 131 pylons.c.form = create_movie_form > 132 return dict(modelname='Movie', page='ToscaTuto') > 133 > 134 Run the application, surf to `http://localhost:8080/new/ `_ You > will see a form that looks like this: > > line 127 duplicates an import pylons line at the top of the file > in the tgz archive. > > > And line 134 took hours to resolve: > the "/new/" should read "/new" (at least on my machine). > > I can access > http://localhost:8080/index/ > and get the same functionality as > http://localhost:8080/index > > but > * http://localhost:8080/new/ > * http://localhost:8080/create/ > both present the form but give an error when a save is attempted, > error message is: > "new() (or create()) accepts at most one non-keyword argument (two > given)". > > What does work fine is: > > * http://localhost:8080/new > * http://localhost:8080/create > > Please take out that final "/" to spare others the hours > it wasted for me!. > > > postscript - > I learned a lot more from the first tutorial than the second > as I had to set the files in the first one up. > Working through the second just amounted to reading through the > instructions > (as everthing was configured already in the downloaded files) - > and that happens too fast except for when typos get in the way. > Because the second app is set up slightly differently than the first > > $ paster quickstart (wiki20) > and > $ paster setup-app (toscawidgets) > > it wasn't initially clear how to reproduce the build situation of the > first > tutorial for the second - the directory structures are different. > > Either way, I was in no position to debug it (that "new/" catch) > as I had no clue what was going on. > (Hence resorting to sqlite at the command line to see what was > wrong with the tables.) > > Anyway, hope this is all of some help. > > Anita >
hi, I just replied to your turbogears list mail, with the links to the sources of each of the wiki20 files, could you please provide this info in that format? if you can't I'll go over your email this weekend and update the documents accordingly. Thanks for this work! --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears Docs" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/turbogears-docs?hl=en -~----------~----~----~----~------~----~------~--~---
