Skip to content
This repository
Browse code

Wiki-20 tutorial changes have begun, code_ext is now working as desir…

…ed. Saving work.
  • Loading branch information...
commit 6bd9fea3170737168517f85163951165547aa7d0 1 parent f2e19c7
Michael Pedersen authored August 04, 2011
1  .gitignore
@@ -19,3 +19,4 @@ docs/project_code/tosca_forms/toscasample/public/movies/
19 19
 docs/project_code/tosca_forms/devdata.db
20 20
 docs/main/Pagination/*.zip
21 21
 book/_build
  22
+wiki20.zip
139  book/appendices/commandline.rst
Source Rendered
... ...
@@ -0,0 +1,139 @@
  1
+==================================
  2
+TurboGears2 Command Line Reference
  3
+==================================
  4
+
  5
+
  6
+TurboGears2 delegates its command line tasks to Paste.  TG1.x uses the
  7
+built-in command ``tgadmin`` which was dropped in favor of the more
  8
+robust Paste infrastructure.
  9
+
  10
+What is PasteScript?
  11
+====================
  12
+
  13
+PasteScript is a part of the Paste group of libraries, which provides
  14
+the very basic foundation on which TurboGears and Pylons are
  15
+built. You can think of Paste_ as a very useful group of things.
  16
+
  17
+.. _Paste: http://pythonpaste.org/
  18
+
  19
+As for PasteScript_ it is composed of two parts Templates and Commands,
  20
+the first takes care of code generation tasks (like quickstart), the
  21
+second is an extensible command line utility (like tginfo)
  22
+
  23
+.. _PasteScript: http://pythonpaste.org/script/
  24
+
  25
+If you are interested in learning how to build your own Paster command
  26
+please visit http://pythonpaste.org/script/developer.html
  27
+
  28
+How Does It Integrate With TurboGears 2?
  29
+========================================
  30
+
  31
+PasteScript provides a single command-line script named ``paster``
  32
+which is built to be self-explanatory.  Try it out on the command
  33
+line: it should give you a big list of commands. There is also a
  34
+``paster help <command>`` command that will give you additional
  35
+information about all commands that it provides.
  36
+
  37
+Using a setuptools mechanism known as "entry point" TurboGears, as
  38
+well as any other project that uses PasteScript, is able to add
  39
+extensions to the paster command; for example if you execute paster
  40
+with no parameters you will see a "TurboGears2" section.
  41
+
  42
+.. _commandline-reference:
  43
+
  44
+What are the TurboGears commands?
  45
+=================================
  46
+
  47
+Please note that not all ``paster`` commands are expected to work with
  48
+a TurboGears |version| project. However, if you experience an error using
  49
+paster we encourage you to report it. Below is a list of the most important
  50
+commands you will use in your journey in the world of TurboGears |version|.
  51
+Be sure to run ``paster help`` on each of them to get all the possible command
  52
+line switches.
  53
+
  54
+====================================  ===========================================
  55
+paster command                        action
  56
+====================================  ===========================================
  57
+`paster quickstart`_ <project_name>   initialize new project
  58
+`paster serve`_  <config_file>        serve project configured in <config_file>
  59
+`paster tginfo`_                      list tg files in current path
  60
+`paster shell`_ <config_file>         start python shell, loading project models
  61
+`paster setup-app`_  <config_file>    initialize project using config_file
  62
+====================================  ===========================================
  63
+
  64
+
  65
+.. _paster quickstart:
  66
+
  67
+paster quickstart
  68
+-----------------
  69
+
  70
+This is probably the first command you will encounter when developing
  71
+on TurboGears, it will create a base project for you with everything
  72
+you need to get started and explanations for everything. In case you
  73
+are wondering this is a small wrapper around ``paster create`` to
  74
+provide a TG1-like command.
  75
+
  76
+.. _paster serve:
  77
+
  78
+paster serve
  79
+------------
  80
+
  81
+This is used to start the built-in server.  This is a very robust
  82
+implementation (multi-threaded, SSL support, etc.) which means several
  83
+people use it in production. That said, you should take a look at our
  84
+:ref:`tgdeployment` docs. The most common usage for this command is:
  85
+
  86
+.. code-block:: bash
  87
+
  88
+     $ paster serve --reload development.ini
  89
+
  90
+The above command will enable the reloading of the server every time
  91
+you save a file, which is a very nice feature :)
  92
+
  93
+.. _paster tginfo:
  94
+
  95
+paster tginfo
  96
+-------------
  97
+
  98
+This command is designed to display a rather big chunk of information
  99
+regarding your TurboGears installation, and it's designed to
  100
+troubleshoot installation problems. Therefore it should be the first
  101
+thing you should run to be certain your system is healthy.
  102
+
  103
+.. _paster shell:
  104
+
  105
+paster shell
  106
+------------
  107
+
  108
+This starts a python shell with your TurboGears application
  109
+loaded. The most important feature here is that your model is also
  110
+loaded, therefore you can experiment with your database.
  111
+
  112
+.. note::
  113
+
  114
+    Changes made to your database from within `paster shell` are
  115
+    encapsulated in a transaction.  In other words, your changes won't
  116
+    be saved unless you commit::
  117
+
  118
+        import transaction
  119
+	transaction.commit()
  120
+
  121
+.. _paster setup-app:
  122
+
  123
+paster setup-app
  124
+----------------
  125
+
  126
+setup-app provides two crucial pieces of functionality.
  127
+
  128
+1) Set up your database schema.
  129
+2) Add bootstrap data to your database.
  130
+
  131
+Your project will have a folder called websetup which contains
  132
+schema.py and bootstrap.py. Each of these can be customized to add
  133
+additional functionality to your bootstrapping process.  For instance,
  134
+if you have additional default users you would like added, you would
  135
+add them in at the bottom of bootstrap.py inside the bootstrap()
  136
+function, before the transaction.commit().  The command looks
  137
+something like this::
  138
+
  139
+     paster setup-app development.ini
10  book/code_ext.py
@@ -38,8 +38,8 @@
38 38
 import nose
39 39
 
40 40
 
41  
-beginmarker_re = re.compile(r'##\{(?P<section>.+)}')
42  
-endmarker_re = re.compile(r'##')
  41
+beginmarker_re = re.compile(r'##\{B:(?P<section>.+)}')
  42
+endmarker_re = re.compile(r'##\{E:(?P<section>.+)}')
43 43
 already_pulled = False
44 44
 
45 45
 # This is based on 'Multi-line string block formatting' recipe by Brett Levin
@@ -160,9 +160,9 @@ def code_directive(name, arguments, options, content, lineno,
160 160
             sections = [x.strip() for x in options['section'].split(',')]
161 161
             res = []
162 162
             for section in sections:
163  
-                res.extend(format_block(search(data, section)))
164  
-                res.extend('')
165  
-            source = '\n'.join(data)
  163
+                res.append(format_block(search(data, section)))
  164
+                res.append('')
  165
+            source = '\n'.join(res)
166 166
         else:
167 167
             source = format_block('\n'.join(data))
168 168
         retnode = nodes.literal_block(source, source)
2  book/conf.py
@@ -277,4 +277,4 @@
277 277
 }
278 278
 
279 279
 # Custom code_ext config values
280  
-code_url = 'git://github.com/alex/pyvcs.git'
  280
+code_url = 'git://git.code.sf.net/p/turbogears2/tg2tut'
9  book/index.rst
Source Rendered
@@ -2,6 +2,8 @@
2 2
  Building Applications with TurboGears 2
3 3
 =========================================
4 4
 
  5
+.. note:: This page is filled with notes about what each chapter should become. As the chapter gets filled in with a proper document, the notes will be removed, leaving only the clean table of contents. Until then, the notes are left in for future reference.
  6
+
5 7
 #########
6 8
  Preface
7 9
 #########
@@ -24,6 +26,11 @@ Part I - The Basics
24 26
 * Getting TurboGears Installed and Serving Pages
25 27
 * Specifying A Web App To Be Developed Throughout The Book
26 28
 
  29
+.. toctree::
  30
+   :hidden:
  31
+
  32
+   part1/wiki20
  33
+
27 34
 ##########################
28 35
 Part II - Making A Web App
29 36
 ##########################
@@ -77,6 +84,7 @@ Part IV - Alternatives and Extensions
77 84
 Appendices
78 85
 ##########
79 86
 
  87
+* :doc:`appendices/commandline`
80 88
 * Multiple Domains Served by Single TG2 Application Instance
81 89
 * Testing and Debugging TG2 Applications
82 90
 * External Tutorials
@@ -97,6 +105,7 @@ Appendices
97 105
    :hidden:
98 106
    :glob:
99 107
 
  108
+   appendices/commandline
100 109
    appendices/preprelease
101 110
    appendices/modules/*
102 111
    
51  book/part1/wiki20.rst
Source Rendered
@@ -2,11 +2,15 @@
2 2
 Whetting the Appetite: Make a Wiki in 20 Minutes
3 3
 ================================================
4 4
 
5  
-.. archive:: wiki_root/trunk
  5
+.. archive:: wiki20
  6
+   :root: Wiki-20
6 7
 
7  
-Welcome!  This tutorial will show you how to create a simple wiki with
8  
-TurboGears 2. It is designed to be your first experience with
9  
-TurboGears 2.
  8
+How does TurboGears2 help you get development done quickly? We'll show
  9
+you by developing a simple wiki application that should take you no
  10
+more than 20 minutes to complete. We're going to do this without
  11
+explaining the steps in detail (that is what this book is for, after
  12
+all). As a result, you'll see how easily you can make your own web
  13
+applications once you are up to speed on what TurboGears2 offers.
10 14
 
11 15
 If you're not familiar with the concept of a wiki you might want to
12 16
 check out `the Wikipedia entry <http://en.wikipedia.org/wiki/Wiki>`_.
@@ -27,7 +31,7 @@ suggestions for improvement of the docs, not for seeking support.
27 31
 If you want to see the final version you can download a copy of the
28 32
 `wiki code`_.
29 33
 
30  
-.. _`wiki code`: ../../_static/tutorials/Wiki-20.zip
  34
+.. _`wiki code`: ../_static/wiki20.zip
31 35
 
32 36
 .. _TurboGears discussion list: http://groups.google.com/group/turbogears
33 37
 
@@ -38,11 +42,13 @@ Setup
38 42
 
39 43
 To go through this tutorial, you'll need:
40 44
 
41  
-#.  Python_ 2.4, 2.5 or 2.6.  Note that Mac OSX 10.5 (Leopard)
42  
-    comes with Python 2.5 pre-installed; for 10.4 and
43  
-    before, follow *Macintosh* in the above link.
  45
+#.  Python_ 2.4, 2.5, 2.6 or 2.7.  Note that Mac OSX 10.5 (Leopard)
  46
+    comes with Python 2.5 pre-installed.
44 47
 
45  
-#.  :ref:`downloadinstall`
  48
+#.  virtualenv_. Not that on many Linux based systems you will need to
  49
+    install a Python development package for this to work, such as
  50
+    python-devel or python-dev. In addition, virtualenv is available
  51
+    via most package managers, so can be installed that way.
46 52
 
47 53
 #.  docutils_ 0.4 or later,
48 54
     which is used for the wiki's formatting. ``docutils`` is not a required
@@ -86,6 +92,7 @@ This tutorial doesn't cover Python at all. Check the `Python
86 92
 Documentation`_ page for more coverage of Python.
87 93
 
88 94
 .. _Python: http://www.python.org/download/
  95
+.. _virtualenv: http://pypi.python.org/pypi/virtualenv
89 96
 .. _docutils: http://cheeseshop.python.org/pypi/docutils
90 97
 .. _ipython shell: http://ipython.scipy.org/
91 98
 .. _ipython docs: http://ipython.scipy.org/moin/Documentation
@@ -95,12 +102,12 @@ Documentation`_ page for more coverage of Python.
95 102
 Quickstart
96 103
 ==========
97 104
 
98  
-TurboGears provides a suite of tools for working with projects by
  105
+TurboGears2 provides a suite of tools for working with projects by
99 106
 adding several commands to the Python command line tool ``paster``. A
100  
-few will be touched upon in this tutorial. (Check the :ref:`Command
101  
-Line Reference <commandline-reference>` for a full listing.) The first
102  
-tool you'll need is ``quickstart``, which initializes a TurboGears
103  
-project.  Go to a command line window and run the following command::
  107
+few will be touched upon in this tutorial. (Check the
  108
+:doc:`../appendices/commandline` for a full listing.) The first tool
  109
+you'll need is ``quickstart``, which initializes a TurboGears project.
  110
+Go to a command line window and run the following command::
104 111
 
105 112
     $ paster quickstart
106 113
 
@@ -113,16 +120,18 @@ choices for this tutorial look like::
113 120
 
114 121
     $ paster quickstart
115 122
     Enter project name: Wiki 20
116  
-    Enter package name [wiki20]: wiki20
117  
-    Do you need authentication and authorization in this project? [yes] no
  123
+    Enter package name [wiki20]: 
  124
+    Would you prefer mako templates? (yes/[no]): no
  125
+    Do you need authentication and authorization in this project? ([yes]/no): no
118 126
 
  127
+    
119 128
 We recommend you use the names given here: this documentation looks
120 129
 for files in directories based on these names.
121 130
 
122 131
 Now ``paster`` will spit out a bunch of stuff::
123 132
 
124 133
   Selected and implied templates:
125  
-    tg.devtools#turbogears2  TurboGears 2.1 Standard Quickstart Template
  134
+    tg.devtools#turbogears2  TurboGears 2. Standard Quickstart Template
126 135
 
127 136
   ...etc...
128 137
 
@@ -137,6 +146,13 @@ directory name "Wiki-20".  Go in there and take a look around::
137 146
 
138 147
     $ cd Wiki-20
139 148
 
  149
+You need to update the dependencies in the file "setup.py". Currently,
  150
+it looks like this:
  151
+
  152
+.. code:: Wiki-20/setup.py
  153
+   :revision: f8464682ad9c5f4c3b6a31211a038468a2caba95
  154
+   :section: setupdeps
  155
+
140 156
 Now to be able to run the project you will need to install it and
141 157
 its dependencies. This can be quickly achieved by running from
142 158
 inside the ``Wiki-20`` directory::
@@ -274,6 +290,7 @@ Since a wiki is basically a linked collection of pages, we'll define a
274 290
 
275 291
 .. code:: README.txt
276 292
 
  293
+
277 294
 In order to easily use our model within the application, modify the
278 295
 `Wiki-20/wiki20/model/__init__.py` file to add ``Page`` and
279 296
 ``pages_table`` to the module. Add the following line *at the end of

0 notes on commit 6bd9fea

Please sign in to comment.
Something went wrong with that request. Please try again.