[IMP] step through *working* instructions in the first section

4 files changed, 59 insertions, 39 deletions

diff --git a/doc/howto/howto_website.rst b/doc/howto/howto_website.rst
index f4c2c7f6f47..e6494bea138 100644
--- a/doc/howto/howto_website.rst
+++ b/doc/howto/howto_website.rst
@@ -43,33 +43,62 @@ right next to your server's directory:
     └── security
         └── ir.model.access.csv
 
+* ``academy`` is the root directory of your module
+* ``__init__.py`` tells Python that it is a valid package, and imports
+  sub-packages and sub-modules
+* ``__openerp__.py`` provides various meta-information about your module to
+  OpenERP (a short description, the module's dependencies, its author, its
+  version, ...)
+* ``controllers`` holds the object responding to web (browser) requests
+  - ``academy.py`` is where a default controller has been created for you
+* ``models`` holds OpenERP stored objects, ignore it for now, we'll dive into
+  it when `storing data in OpenERP`
+* ``ir.model.access.csv`` defines basic access rights to the models, you can
+  also ignore it for now
+
 .. patch::
     :hidden:
 
-.. todo::
+Now we can create a database, start your OpenERP server and install your new
+module in it:
 
-   * instructions for start & install
-   * db handling
+.. code-block:: console
 
-     - if existing db, automatically selected
-     - if no existing db, nodb -> login -> login of first db
-     - dbfilter
+    $ createdb academy
+    $ ./openerp-server --addons-path=../web/addons,../addons,../my-modules \
+                       -d academy -i academy --db-filter=academy
 
-Now start your OpenERP server and install your module in it, open a web
-browser and navigate to http://localhost:8069. A page should appear with just
-the words "Hello, world!" on it.
+* ``--addons-path`` tells OpenERP where it can find its modules. By default it
+  will only look into ``openerp/addons``, this adds the web client modules,
+  the "standard" business modules (not needed yet) and the place where your
+  own ``academy`` module lives.
+* ``-i`` installs the provided module name in the database specified via
+  ``-d``
+* ``--db-filter`` means the specified database will be selected by default in
+  the web interface, and will be the only one selectable (makes starting
+  things up simpler)
 
-.. todo:: screenshot?
+Once the installation is finished you should see ``HTTP service (werkzeug)
+running on 0.0.0.0:8069`` and nothing more happening in the log. You can now
+open a web browser and navigate to http://localhost:8069. A page should
+appear with just the words "Hello, world!" on it:
 
-Let's prettify things a bit: instead of returning just a bit of text,
-we can return a page, and use a tool like bootstrap_ to get a
-nicer rendering than the default.
+.. image:: howto_website/helloworld.png
 
-Go to :file:`academy/controllers/academy.py` and change the string
-returned by the ``index`` method to get a more page-ish output:
+This page is generated by the ``index`` method in
+:file:`academy/controllers/academy.py`, which just returns some text. Let's
+make it prettier by returning HTML and using bootstrap_ to get a nicer default
+rendering:
 
 .. patch::
 
+Restart the server, refresh the page
+
+.. image:: howto_website/hellobootstrap.png
+
+Although it is subtle for so little text and markup, the font has changed and
+margins have been added to the page.
+
 .. note::
 
    this example requires internet access as we're accessing a :abbr:`CDN
@@ -77,23 +106,13 @@ returned by the ``index`` method to get a more page-ish output:
    and trying to provide high-performance and high-availability of these
    files)`-hosted file.
 
-.. todo:: screenshot
-
 Controller Parameters
 =====================
 
-Being able to build a static page in code is nice, but makes for limited
-usefulness (you could do that with static files).
-
-You can also create dynamic pages which use data provided in the URL,
-for instance so a single controller generates multiple pages. Any
-query parameter (``?name=value``) is passed as a string parameter to the
-controller method.
-
-For instance, the index page can display a list of teaching assistants linking
-to a page for each assistant through their index in a global array. Each
-assistant's page will simply print their name by applying the index to the
-array:
+For dynamic pages, query parameters are passed as string parameters to the
+controller method. For instance the index page can display a list of teaching
+assistants, and link to each assistant's page using an index (in a global
+array for now):
 
 .. patch::
 
@@ -103,15 +122,15 @@ formatted. For this reason, query parameters are generally used to provide
 "options" to a given page, and "required" data tends (when possible) to be
 inserted directly in the URL.
 
-This can be done by adding `converter patterns`_ to the URL in
-``@http.route``:
+This we can do by adding `converter patterns`_ to the URL in ``@http.route``:
 
 .. patch::
 
-These patterns can perform conversions directly (in this case the conversion
-from a string URL section to a python integer) and will perform a some
-validation (if the ``id`` is not a valid integer, the converter will return a
-``404 Not Found`` instead of a 500 server error when the conversion fails).
+These patterns will generally do some validation (e.g. if the ``id`` is not
+a valid integer the converter will result in a ``404 Not Found`` page instead
+of a 500 server error when the conversion failed in our own code) and may
+perform some parsing or type conversion (in this case the conversion from a
+URL section — a string — to a Python integer).
 
 Basic templates
 ===============
diff --git a/doc/howto/howto_website/basic-page b/doc/howto/howto_website/basic-page
index 5e053dcdea2..d3179145542 100644
--- a/doc/howto/howto_website/basic-page
+++ b/doc/howto/howto_website/basic-page
@@ -12,6 +12,6 @@ diff --git a/controllers/academy.py b/controllers/academy.py
 +        return """<!doctype html>
 +<link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
 +<body class="container">
-+    <h1>Introduction to a thing</h1>
++    Hello, world!
 +</body>
 +"""
diff --git a/doc/howto/howto_website/ta-controller b/doc/howto/howto_website/ta-controller
index e3fef6d3486..64de1dae17b 100644
--- a/doc/howto/howto_website/ta-controller
+++ b/doc/howto/howto_website/ta-controller
@@ -27,7 +27,8 @@ diff --git a/controllers/academy.py b/controllers/academy.py
          return """<!doctype html>
  <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
  <body class="container">
-     <h1>Introduction to a thing</h1>
+-    Hello, world!
++    <h1>Introduction to something</h1>
 +    <h2>Teaching Assistants</h2>
 +    <ul>
 +        %(tas)s
diff --git a/doc/howto/howto_website/templates-basic b/doc/howto/howto_website/templates-basic
index b857b214f94..2fb934bdbb0 100644
--- a/doc/howto/howto_website/templates-basic
+++ b/doc/howto/howto_website/templates-basic
@@ -1,5 +1,5 @@
 # HG changeset patch
-# Parent 93586905ed9663bf48ef33ca6476a537a8f96ac8
+# Parent c6916a09fd20a67c210369676c78f23704870c8e
 
 diff --git a/__openerp__.py b/__openerp__.py
 --- a/__openerp__.py
@@ -32,7 +32,7 @@ diff --git a/controllers/academy.py b/controllers/academy.py
 -        return """<!doctype html>
 -<link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
 -<body class="container">
--    <h1>Introduction to a thing</h1>
+-    <h1>Introduction to something</h1>
 -    <h2>Teaching Assistants</h2>
 -    <ul>
 -        %(tas)s