tutorial typos (wiki20 and toscawidgets)
1 view
Skip to first unread message
akean
Jan 4, 2009, 8:04:00 PM1/4/09
to TurboGears Docs
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
Jorge Vargas
Jan 5, 2009, 8:19:28 PM1/5/09
to turboge...@googlegroups.com
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!
anita kean
Jan 13, 2009, 3:11:24 AM1/13/09
to TurboGears Docs
Hello turbogears folks
I've volunteered to help out with moving the turbogears1.x
docs over to sphinx.
Felix Schwarz has kindly given me access to the docs in an
initial rst form.
Short of installing tg1 on my system, where can I download
a browsable form of the tg1 docs so that I know what I'm
working towards?
(Yes I've found them online - but I'd like a local copy
for convenience.)
Thanks
Anita
Felix Schwarz
Jan 13, 2009, 4:18:01 AM1/13/09
to turboge...@googlegroups.com
anita kean schrieb:
> Felix Schwarz has kindly given me access to the docs in an
> initial rst form.
> Short of installing tg1 on my system, where can I download
> a browsable form of the tg1 docs so that I know what I'm
> working towards?
> Felix Schwarz has kindly given me access to the docs in an
> initial rst form.
> Short of installing tg1 on my system, where can I download
> a browsable form of the tg1 docs so that I know what I'm
> working towards?
Actually there is a nightly snapshot linked on the main docs page:
http://docs.turbogears.org/
fs
anita kean
Jan 13, 2009, 4:36:20 AM1/13/09
to turboge...@googlegroups.com
I thought I'd looked everywhere.
--
Anita
Reply all
Reply to author
Forward
0 new messages