First 2 steps on tutorial, make html runs without complaint. Each ste…

…p is now its own package.
Pylons · Jun 22, 2012 · e9b47a9 · e9b47a9
1 parent 5c67798
commit e9b47a9
Show file tree

Hide file tree

Showing 16 changed files with 392 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -10,3 +10,4 @@ dist/
 .tox/
 nosetests.xml
 env*/
+Data.fs*
diff --git a/docs/index.rst b/docs/index.rst
@@ -67,6 +67,14 @@ API Documentation
 
    api.rst
 
+Tutorial Documentation
+----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorial/index.rst
+
 Reporting Bugs / Development Versions
 -------------------------------------
 

diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
@@ -0,0 +1,20 @@
+Substance D Tutorial
+====================
+
+With Substance D you get lots of machinery to build a content-oriented
+application, along with a UI to help manage the content.
+
+What is included in that machinery? This hands-on tutorial covers a
+little about a lot: practical introductions to the most common
+facilities.  Fun, fast-paced, and most certainly not aimed at experts.
+Along the way we will assemble a sample application.
+
+Steps
+-----
+
+.. toctree::
+   :maxdepth: 1
+
+   setup.rst
+   step01.rst
+   step02.rst
diff --git a/docs/tutorial/setup.rst b/docs/tutorial/setup.rst
@@ -0,0 +1,44 @@
+==============
+Tutorial Setup
+==============
+
+This tutorial presumes you have Python 2.6 or higher, a network
+connection, and the editor of your choice. The following is enough to
+get you started on the first step. Other steps might ask to install
+extra packages.
+
+.. note::
+
+   Windows users will need to adapt the Unix-isms below to match
+   their environment.
+
+Each "step" in the tutorial is its own Python package. Thus,
+at the start of each tutorial step, you will see a reminder to
+develop-install that step.
+
+Steps
+=====
+
+#. Open a shell window and ``cd`` to a working directory.
+
+#. ``$ mkdir tutorial_workspace; cd tutorial_workspace``
+
+#. ``$ virtualenv env``
+
+#. ``$ export PATH=/path/to/tutorial_workspace/env/bin:$PATH``
+
+#. ``$ which easy_install``
+
+   This should report the ``easy_install`` from ``env/bin``.
+
+
+Code Examples
+=============
+
+Each step in the tutorial asks the reader to enter code examples and
+produce a working application. The directories for these steps are
+*Python packages*: fully-working, standalone examples that demonstrate
+the topic being discussed.
+
+The example files are available for those that don't want to enter the
+code as part of the tutorial process.
diff --git a/docs/tutorial/step01.rst b/docs/tutorial/step01.rst
@@ -0,0 +1,70 @@
+===============================
+Step 01: Hello World in Pyramid
+===============================
+
+Before we get into Substance D, we need to get Pyramid installed and a
+sample application working.
+
+Goals
+=====
+
+- Get Pyramid pixels on the screen as easily as possible
+
+- Use that as a well-understood base for adding each unit of complexity
+
+Objectives
+==========
+
+- Create a module with a view that acts as an HTTP server
+
+- Visit the URL in your browser
+
+Background
+==========
+
+Microframeworks are all the rage these days. They provide low-overhead
+on execution. But also, they have a low mental overhead: they do so
+little, the only things you have to worry about are *your things*.
+
+Pyramid is special because it can act as a single-file module
+microframework. You have a single Python file that can be executed
+directly by Python. But Pyramid also scales to the largest of
+applications.
+
+Steps
+=====
+
+#. Make sure you have followed the steps in :doc:`setup`.
+
+#. ``$ mkdir step01; cd step01``
+
+#. Copy the following into ``step01/setup.py``:
+
+   .. literalinclude:: step01/setup.py
+      :linenos:
+
+#. Copy the following into ``step01/setup.cfg``:
+
+   .. literalinclude:: step01/setup.cfg
+      :linenos:
+
+#. Copy the following into ``step01/development.ini``:
+
+   .. literalinclude:: step01/development.ini
+      :linenos:
+
+#. ``mkdir tutorial; cd tutorial``
+
+#. Copy the following into ``step01/tutorial/__init__.py``:
+
+   .. literalinclude:: step01/tutorial/__init__.py
+      :linenos:
+
+#. ``cd ..; python ./setup.py develop``
+
+   *Make sure you are using the Python from your virtualenv!*
+
+#. ``$ pserve development.ini``
+
+#. Open ``http://127.0.0.1:6543/`` in your browser.
+
diff --git a/docs/tutorial/step01/development.ini b/docs/tutorial/step01/development.ini
@@ -0,0 +1,7 @@
+[app:main]
+use = call:tutorial:main
+
+[server:main]
+use = egg:waitress#main
+host = 0.0.0.0
+port = 6543
diff --git a/docs/tutorial/step01/setup.cfg b/docs/tutorial/step01/setup.cfg
@@ -0,0 +1,27 @@
+[nosetests]
+match = ^test
+nocapture = 1
+cover-package = tutorial
+with-coverage = 1
+cover-erase = 1
+
+[compile_catalog]
+directory = tutorial/locale
+domain = tutorial
+statistics = true
+
+[extract_messages]
+add_comments = TRANSLATORS:
+output_file = tutorial/locale/tutorial.pot
+width = 80
+
+[init_catalog]
+domain = tutorial
+input_file = tutorial/locale/tutorial.pot
+output_dir = tutorial/locale
+
+[update_catalog]
+domain = tutorial
+input_file = tutorial/locale/tutorial.pot
+output_dir = tutorial/locale
+previous = true
diff --git a/docs/tutorial/step01/setup.py b/docs/tutorial/step01/setup.py
@@ -0,0 +1,34 @@
+import os
+
+from setuptools import setup, find_packages
+
+here = os.path.abspath(os.path.dirname(__file__))
+
+requires = [
+    'pyramid',
+    'waitress',
+    'substanced',
+    'pyramid_tm',
+    ]
+
+setup(name='tutorial',
+      version='0.0',
+      description='SubstanceD Tutorial',
+      classifiers=[
+          "Programming Language :: Python",
+          "Framework :: Pylons",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+          ],
+      author='',
+      author_email='',
+      url='',
+      keywords='web pyramid pylons substanced',
+      packages=find_packages(),
+      include_package_data=True,
+      zip_safe=False,
+      install_requires=requires,
+      tests_require=requires,
+      test_suite="tutorial",
+      )
+
diff --git a/docs/tutorial/step01/tutorial/__init__.py b/docs/tutorial/step01/tutorial/__init__.py
@@ -0,0 +1,11 @@
+from pyramid.config import Configurator
+from pyramid.response import Response
+
+# This acts as the view function
+def hello_world(request):
+    return Response('hello!')
+
+def main(global_config, **settings):
+    config = Configurator()
+    config.add_view(hello_world)
+    return config.make_wsgi_app()
diff --git a/docs/tutorial/step02.rst b/docs/tutorial/step02.rst
@@ -0,0 +1,67 @@
+===================================
+Step 02: Hello World in Substance D
+===================================
+
+Substance D adds quite a bit atop Pyramid. In this step we do the
+minimum to bootstrap Substance D and let you start poking around.
+
+Goals
+=====
+
+- Get Substance D pixels on the screen as easily as possible
+
+- Use that as a well-understood base for adding each unit of complexity
+
+Objectives
+==========
+
+- Include Substanced D into your ``Configurator``
+
+- Use a ``substanced.site.Site.root_factory`` as your ``root_factory``
+
+Steps
+=====
+
+#. ``$ cp -r step01 step 02; cd step02; python setup.py develop``
+
+#. Copy the following into ``step02/development.ini``:
+
+   .. literalinclude:: step02/development.ini
+      :linenos:
+
+#. Copy the following into ``step02/tutorial/__init__.py``:
+
+   .. literalinclude:: step02/tutorial/__init__.py
+      :linenos:
+
+#. Copy the following into ``step02/tutorial/views.py``:
+
+   .. literalinclude:: step02/tutorial/views.py
+      :linenos:
+
+#. ``mkdir templates``
+
+#. Copy the following into ``step02/tutorial/templates/hello.pt``:
+
+   .. literalinclude:: step02/tutorial/templates/hello.pt
+      :linenos:
+
+#. ``$ pserve development.ini``
+
+#. Open ``http://127.0.0.1:6543/`` in your browser.
+
+At this point you'll see ``Hello, Little Dummy`` on your screen. But
+perhaps you also noticed that your ``step02`` directory grew some new
+files: ``Data.fs``, ``Data.fs.index``, etc. What's that all about?
+
+SDI, the Substance D Interface
+==============================
+
+#. Open ``http://127.0.0.1:6543/manage/`` in your browser.
+
+#. Login with username ``admin`` and password ``admin``.
+
+This is the management UI for Substance D, and a visualization of the
+content-oriented approach to building applications. As you click
+through and add content, the object database is storing your resources
+transactionally.
diff --git a/docs/tutorial/step02/development.ini b/docs/tutorial/step02/development.ini
@@ -0,0 +1,19 @@
+[app:main]
+use = call:tutorial:main
+
+pyramid.reload_templates = true
+pyramid.includes =
+    pyramid_tm
+
+zodbconn.uri = file://%(here)s/Data.fs?connection_cache_size=20000
+substanced.secret = seekri1
+substanced.initial_login = admin
+substanced.initial_password = admin
+substanced.uploads_tempdir = %(here)s/tmp
+
+mail.default_sender = substanced_demo@pylonsproject.org
+
+[server:main]
+use = egg:waitress#main
+host = 0.0.0.0
+port = 6543
diff --git a/docs/tutorial/step02/setup.cfg b/docs/tutorial/step02/setup.cfg
@@ -0,0 +1,27 @@
+[nosetests]
+match = ^test
+nocapture = 1
+cover-package = tutorial
+with-coverage = 1
+cover-erase = 1
+
+[compile_catalog]
+directory = tutorial/locale
+domain = tutorial
+statistics = true
+
+[extract_messages]
+add_comments = TRANSLATORS:
+output_file = tutorial/locale/tutorial.pot
+width = 80
+
+[init_catalog]
+domain = tutorial
+input_file = tutorial/locale/tutorial.pot
+output_dir = tutorial/locale
+
+[update_catalog]
+domain = tutorial
+input_file = tutorial/locale/tutorial.pot
+output_dir = tutorial/locale
+previous = true
diff --git a/docs/tutorial/step02/setup.py b/docs/tutorial/step02/setup.py
@@ -0,0 +1,34 @@
+import os
+
+from setuptools import setup, find_packages
+
+here = os.path.abspath(os.path.dirname(__file__))
+
+requires = [
+    'pyramid',
+    'waitress',
+    'substanced',
+    'pyramid_tm',
+    ]
+
+setup(name='tutorial',
+      version='0.0',
+      description='SubstanceD Tutorial',
+      classifiers=[
+          "Programming Language :: Python",
+          "Framework :: Pylons",
+          "Topic :: Internet :: WWW/HTTP",
+          "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+          ],
+      author='',
+      author_email='',
+      url='',
+      keywords='web pyramid pylons substanced',
+      packages=find_packages(),
+      include_package_data=True,
+      zip_safe=False,
+      install_requires=requires,
+      tests_require=requires,
+      test_suite="tutorial",
+      )
+