Permalink
Browse files

updated docs, v1.0

  • Loading branch information...
1 parent a085f68 commit 0170e95a8a75af1e8c42d629227d6d8459885708 @fiorix committed Dec 31, 2012
View
@@ -96,7 +96,7 @@ cyclone can be installed from ``pip`` or ``easy_install``::
$ pip install cyclone
It has no external dependencies other than Twisted 10 or newer, running
-on Python 2.6 or 2.7, or PyPy 1.8 or 1.9.
+on Python 2.6 or 2.7, or PyPy 1.8, 1.9, or newer.
It runs on Python 2.5 too, but requires the ``simplejson`` module. Also, it
runs on PyPy 1.8 as long as there's no SSL.
@@ -138,6 +138,10 @@ A dev server can be started like this::
reactor class: twisted.internet.selectreactor.SelectReactor.
cyclone.web.Application starting on 8888
+ or
+
+ $ cyclone run -r hello.Application
+
Due to the power of ``twistd``, cyclone apps can be easily deployed in
production, with all the basic features of standard daemons::
@@ -185,7 +189,7 @@ and HTML templates.
::
- $ python -m cyclone.app --help
+ $ cyclone app --help
use: cyclone.app [options]
Options:
@@ -195,26 +199,36 @@ and HTML templates.
-m --modname=NAME Use another name for the module [default: project_name]
-v --version=VERSION Set project version [default: 0.1]
-s --set-pkg-version Set version on package name [default: False]
- -t --target=PATH Set path where project is created [default: ./]
+ -t --target=PATH Set path where project is created [default: /Users/alef/dev/web/cyclone]
-l --license=FILE Append the following license file [default: Apache 2]
- -f --foreman Create a foreman based project (suited to run on heroku and other PaaS)
+ -a --appskel=SKEL Set the application skeleton [default: default]
+
+ Appskel:
+ default Basic cyclone project
+ signup Basic sign up/in/out, password reset, etc
+ foreman Create a foreman based project (suited to run on heroku and other PaaS)
Creating new projects can be as simple as running this::
- $ python -m cyclone.app -p foobar
+ $ cyclone app -g -p foobar
-Check README.rst in the new project directory for detailed information on how
+Check README.md in the new project directory for detailed information on how
to use it.
The template ships with Debian init scripts for running ``twistd`` as single,
or multiple instances (one per CPU core) to help make deployments as simple as
possible.
-If you are into PaaS (heroku for example) or just using foreman to manage your applications, create your application like this ::
-
- $ python -m cyclone.app -f -p foobar
+If you are into PaaS (heroku for example) or just using foreman to manage your
+applications, create your application like this::
+
+ $ cyclone app -g -p foobar -a foreman
+
+and check the README.md for further instructions.
+
+And, for a more complex application with sign up, password reset, use this::
-and check the README.rst for further instructions.
+ $ cyclone app -g -p foobar -a signup
Tips and Tricks
@@ -418,7 +432,7 @@ There is a complete example of internationalized web application in
Also, the project template that ships with cyclone is already prepared for
full translation. Give it a try::
- $ python -m cyclone.app -p foobar
+ $ cyclone app -g -p foobar
Then check the contents of ``foobar/``.
View
@@ -1,23 +1,20 @@
# cyclone-based project
- This is the source code of $project_name
- $name <$email>
+ This is the source code of $project_name
+ $name <$email>
+
## About
-This file has been created automatically by cyclone-tool for $project_name.
-It contains the following files:
+This file has been created automatically by cyclone for $project_name.
+It contains the following:
-- ``start.sh``: simple shell script to start the server
+- ``start.sh``: simple shell script to start the development server
- ``$modname.conf``: configuration file for the web server
-- ``$modname/__init__.py``: information such as author and version of this package
-- ``$modname/web.py``: map of url handlers and main class of the web server
-- ``$modname/config.py``: configuration parser for ``$modname.conf``
-- ``$modname/views.py``: code of url handlers for the web server
-- ``scripts/debian-init.d``: generic debian start/stop init script
-- ``scripts/debian-multicore-init.d``: run one instance per core on debian
-- ``scripts/localefix.py``: script to fix html text before running ``xgettext``
-- ``scripts/cookie_secret.py``: script for generating new secret key for the web server
+- ``$modname/``: web server code
+- ``frontend/``: static files, templates and locales
+- ``scripts/``: debian init scripts and other useful scripts
+
### Running
@@ -26,36 +23,30 @@ For development and testing:
twistd -n cyclone --help
twistd -n cyclone -r $modname.web.Application [--help]
-For production:
-
- twistd cyclone \
- --logfile=/var/log/$project.log \
- --pidfile=/var/run/$project.pid \
- -r $modname.web.Application
+ or just run ./start.sh
-### Convert this document to HTML
-
-Well, since this is a web server, it might be a good idea to convert this document
-to HTML before getting into customization details.
+For production:
-This can be done using [markdown](http://daringfireball.net/projects/markdown/).
+ twistd cyclone \
+ --logfile=/var/log/$project.log \
+ --pidfile=/var/run/$project.pid \
+ -r $modname.web.Application
- brew install markdown
- markdown README.md > frontend/static/readme.html
+ or check scripts/debian-init.d and scripts/debian-multicore-init.d
-And point your browser to <http://localhost:8888/static/readme.html> after this server
-is running.
## Customization
-This section is dedicated to explaining how to customize your brand new package.
+This section is dedicated to explaining how to customize your brand new
+package.
+
### Databases
cyclone provides built-in support for SQLite and Redis databases.
-It also supports any RDBM supported by the ``twisted.enterprise.adbapi`` module,
-like MySQL or PostgreSQL.
+It also supports any RDBM supported by the ``twisted.enterprise.adbapi``
+module, like MySQL or PostgreSQL.
The default configuration file ``$modname.conf`` ships with pre-configured
settings for SQLite, Redis and MySQL.
@@ -64,7 +55,7 @@ The code for loading all the database settings is in ``$modname/config.py``.
Feel free to comment or even remove such code, and configuration entries. It
shouldn't break the web server.
-Take a look at ``$modname/utils.py``, which is where persistent database
+Take a look at ``$modname/storage.py``, which is where persistent database
connections are initialized.
@@ -89,8 +80,7 @@ If you already use HomeBrew, run:
For generating translatable files for HTML and Python code of your software,
run this:
- cat frontend/template/*.html $modname/*.py | python scripts/localefix.py | \
- xgettext - --language=Python --from-code=utf-8 --keyword=_:1,2 -d $modname
+ cat frontend/template/*.html $modname/*.py | python scripts/localefix.py | xgettext - --language=Python --from-code=utf-8 --keyword=_:1,2 -d $modname
Then translate $modname.po, compile and copy to the appropriate locale
directory:
View
@@ -1,21 +1,21 @@
# cyclone-based project for heroku and other PaaS based on foreman.
- This is the source code of $project_name
- $name <$email>
+ This is the source code of $project_name
+ $name <$email>
+
## About
-This file has been created automatically by cyclone-tool for $project_name.
-It contains the following files:
+This file has been created automatically by cyclone for $project_name.
+It contains the following:
- ``Procman``: standard foreman file
+- ``start.sh``: simple shell script to start the development server
- ``$modname.conf``: configuration file for the web server
-- ``$modname/__init__.py``: information such as author and version of this package
-- ``$modname/web.py``: map of url handlers and main class of the web server
-- ``$modname/config.py``: configuration parser for ``$modname.conf``
-- ``$modname/views.py``: code of url handlers for the web server
-- ``scripts/localefix.py``: script to fix html text before running ``xgettext``
-- ``scripts/cookie_secret.py``: script for generating new secret key for the web server
+- ``$modname/``: web server code
+- ``frontend/``: static files, templates and locales
+- ``scripts/``: other useful scripts
+
### Running
@@ -25,42 +25,33 @@ For development and testing:
cd $project_name
foreman start
-For production on any foreman based env:
-
- Follow foreman instructions, configure Procman as needed. Check the .env file and the configuration file for your app.
+For production on any foreman based env:
+
+ Follow foreman instructions, configure Procman as needed.
+ Check the .env file and the configuration file for your app.
For production at heroku:
-
+
- Start a git repo
git init
git add .
git commit -m 'first'
heroku create $project_name (or whatever name you want)
git push heroku master
- - check your app, make it better, create a db, etc
-
-### Convert this document to HTML
+ - check your app, make it better, create a db, etc
-Well, since this is a web server, it might be a good idea to convert this document
-to HTML before getting into customization details.
-
-This can be done using [markdown](http://daringfireball.net/projects/markdown/).
-
- brew install markdown
- markdown README.md > frontend/static/readme.html
-
-And point your browser to <http://localhost:8888/static/readme.html> after this server
-is running.
## Customization
-This section is dedicated to explaining how to customize your brand new package.
+This section is dedicated to explaining how to customize your brand new
+package.
+
### Databases
cyclone provides built-in support for SQLite and Redis databases.
-It also supports any RDBM supported by the ``twisted.enterprise.adbapi`` module,
-like MySQL or PostgreSQL.
+It also supports any RDBM supported by the ``twisted.enterprise.adbapi``
+module, like MySQL or PostgreSQL.
The default configuration file ``$modname.conf`` ships with pre-configured
settings for SQLite, Redis and MySQL.
@@ -94,8 +85,7 @@ If you already use HomeBrew, run:
For generating translatable files for HTML and Python code of your software,
run this:
- cat frontend/template/*.html $modname/*.py | python scripts/localefix.py | \
- xgettext - --language=Python --from-code=utf-8 --keyword=_:1,2 -d $modname
+ cat frontend/template/*.html $modname/*.py | python scripts/localefix.py | xgettext - --language=Python --from-code=utf-8 --keyword=_:1,2 -d $modname
Then translate $modname.po, compile and copy to the appropriate locale
directory:
View
@@ -1,23 +1,19 @@
# cyclone-based project
- This is the source code of $project_name
- $name <$email>
+ This is the source code of $project_name
+ $name <$email>
## About
-This file has been created automatically by cyclone-tool for $project_name.
-It contains the following files:
+This file has been created automatically by cyclone for $project_name.
+It contains the following:
-- ``start.sh``: simple shell script to start the server
+- ``start.sh``: simple shell script to start the development server
- ``$modname.conf``: configuration file for the web server
-- ``$modname/__init__.py``: information such as author and version of this package
-- ``$modname/web.py``: map of url handlers and main class of the web server
-- ``$modname/config.py``: configuration parser for ``$modname.conf``
-- ``$modname/views.py``: code of url handlers for the web server
-- ``scripts/debian-init.d``: generic debian start/stop init script
-- ``scripts/debian-multicore-init.d``: run one instance per core on debian
-- ``scripts/localefix.py``: script to fix html text before running ``xgettext``
-- ``scripts/cookie_secret.py``: script for generating new secret key for the web server
+- ``$modname/``: web server code
+- ``frontend/``: static files, templates and locales
+- ``scripts/``: debian init scripts and other useful scripts
+
### Running
@@ -26,47 +22,49 @@ For development and testing:
twistd -n cyclone --help
twistd -n cyclone -r $modname.web.Application [--help]
-For production:
-
- twistd cyclone \
- --logfile=/var/log/$project.log \
- --pidfile=/var/run/$project.pid \
- -r $modname.web.Application
-
+ or just run ./start.sh
-### Convert this document to HTML
-Well, since this is a web server, it might be a good idea to convert this document
-to HTML before getting into customization details.
+For production:
-This can be done using [markdown](http://daringfireball.net/projects/markdown/).
+ twistd cyclone \
+ --logfile=/var/log/$project.log \
+ --pidfile=/var/run/$project.pid \
+ -r $modname.web.Application
- brew install markdown
- markdown README.md > frontend/static/readme.html
+ or check scripts/debian-init.d and scripts/debian-multicore-init.d
-And point your browser to <http://localhost:8888/static/readme.html> after this server
-is running.
## Customization
-This section is dedicated to explaining how to customize your brand new package.
+This section is dedicated to explaining how to customize your brand new
+package.
+
### Databases
cyclone provides built-in support for SQLite and Redis databases.
-It also supports any RDBM supported by the ``twisted.enterprise.adbapi`` module,
-like MySQL or PostgreSQL.
+It also supports any RDBM supported by the ``twisted.enterprise.adbapi``
+module, like MySQL or PostgreSQL.
The default configuration file ``$modname.conf`` ships with pre-configured
settings for SQLite, Redis and MySQL.
-The code for loading all the database settings is in ``$modname/config.py``.
-Feel free to comment or even remove such code, and configuration entries. It
-shouldn't break the web server.
+The code for loading all the database settings is in ``$modname/config.py``
+and is required by this application.
-Take a look at ``$modname/utils.py``, which is where persistent database
+Take a look at ``$modname/storage.py``, which is where persistent database
connections are initialized.
+This template uses the experimental ``$modname/txdbapi.py`` for interacting
+with MySQL.
+
+
+### Email
+
+Please edit ``$modname.conf`` and adjust the email settings. This server
+sends email on user sign up, and to reset passwords.
+
### Internationalization
@@ -89,8 +87,7 @@ If you already use HomeBrew, run:
For generating translatable files for HTML and Python code of your software,
run this:
- cat frontend/template/*.html $modname/*.py | python scripts/localefix.py | \
- xgettext - --language=Python --from-code=utf-8 --keyword=_:1,2 -d $modname
+ cat frontend/template/*.html $modname/*.py | python scripts/localefix.py | xgettext - --language=Python --from-code=utf-8 --keyword=_:1,2 -d $modname
Then translate $modname.po, compile and copy to the appropriate locale
directory:
Oops, something went wrong.

0 comments on commit 0170e95

Please sign in to comment.