Merge pull request #257 from kgriffs/master

doc: Add community guide

doc/community/contrib-snip.rst

@@ -0,0 +1,15 @@
+Submit Issues
+-------------
+If you have an idea for a feature, run into something that is harder to
+use than it should be, or find a bug, please let the crew know
+in **#falconframework** and/or by
+`submitting an issue <https://github.com/racker/falcon/issues>`_. We
+need your help to make Falcon awesome!
+
+Pay it Forward
+--------------
+We'd like to invite you to help other community members with their
+questions in IRC, and to peer-review
+`pull requests <https://github.com/racker/falcon/pulls>`_. If you use the
+Chrome browser, we recommend installing the
+`NotHub extension <http://nothub.org/>`_ to stay up to date with PRs.

doc/community/contribute.rst

@@ -0,0 +1,57 @@
+.. _contribute:
+
+Contribute to Falcon
+====================
+
+`Kurt Griffiths <http://kgriffs.com>`_ is the creator and current
+maintainer of the Falcon framework. He works with a growing team of
+friendly and stylish volunteers like yourself, who review patches,
+implement features, fix bugs, and write docs for the project.
+
+Your ideas and patches are always welcome!
+
+IRC
+---
+If you are interested in helping out, please join the **#falconframework**
+IRC channel on `Freenode <https://www.freenode.net/>`_.
+It's the best way to discuss ideas, ask questions, and generally stay
+in touch with fellow contributors. We recommend setting up a good
+IRC bouncer, such as ZNC, which can record and play back any conversations
+that happen when you are away.
+
+.. include:: contrib-snip.rst
+
+Pull Requests
+-------------
+Before submitting a pull request, please ensure you have added new
+tests and updated existing ones as appropriate. We require 100%
+code coverage. Also, please ensure your coding style follows PEP 8 and
+doesn't make pyflakes sad.
+
+**Additional Style Rules**
+
+* Docstrings are required for classes, attributes, methods, and functions.
+* Use `napolean-flavored`_ dosctrings to make them readable both when
+  using the *help* function within a REPL, and when browsing
+  them on *Read the Docs*.
+* Format non-trivial comments using your GitHub nick and an appropriate
+  prefix. Here are some examples:
+    .. code:: python
+
+        # TODO(riker): Damage report!
+        # NOTE(riker): Well, that's certainly good to know.
+        # PERF(riker): Travel time to the nearest starbase?
+        # APPSEC(riker): In all trust, there is the possibility for betrayal.
+
+* Commit messages should be formatted using `AngularJS conventions`_
+  (one-liners are OK for now but bodies and footers may be required as the
+  project matures).
+* When catching exceptions, name the variable ``ex``.
+* Use whitespace to separate logical blocks of code and to improve readability.
+* Do not use single-character variable names except for trivial indexes when
+  looping, or in mathematical expressions implementing well-known formulae.
+* Heavily document code that is especially complex and/or clever.
+* When in doubt, optimize for readability.
+
+.. _napolean-flavored: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html#example-google-style-python-docstrings
+.. _AngularJS conventions: http://goo.gl/QpbS7

doc/community/help.rst

@@ -0,0 +1,20 @@
+.. _help:
+
+Get Help
+========
+
+Welcome to the Falcon community! We are a pragmatic group of HTTP enthusiasts
+working on the next generation of web apps and cloud services. We would love
+to have you join us and share your ideas.
+
+Please help us spread the word and grow the community!
+
+IRC
+---
+While you experiment with Falcon and work to familiarize yourself with
+the WSGI framework, please consider joining the **#falconframework**
+IRC channel on
+`Freenode <https://en.wikipedia.org/wiki/Freenode>`_. It's a great place to
+ask questions, share ideas, and get the scoop on what's new.
+
+.. include:: contrib-snip.rst

doc/index.rst

@@ -77,6 +77,17 @@ Resources
 - `Falcon WSGI Framework: 0.1.8 Highlights <http://blog.kgriffs.com/2014/02/04/falcon-wsgi-framework-highlights-0.1.8.html>`_
 
 
+Community Guide
+---------------
+
+.. toctree::
+   :maxdepth: 1
+
+   community/help
+   community/contribute
+   community/faq
+
+
 User Guide
 ----------
 
@@ -87,19 +98,6 @@ User Guide
    user/install
    user/quickstart
    user/tutorial
-   user/faq
-
-
-.. Community Guide
-.. -----------------
-
-.. *Coming soon*
-
-
-.. Contributor Guide
-.. -----------------
-
-.. *Coming soon*
 
 
 Classes and Functions

doc/user/tutorial.rst

@@ -8,9 +8,6 @@ the way, you will learn about Falcon's features and the terminology used by
 the framework. You'll also learn how to query Falcon's docstrings, and get a
 quick overview of the WSGI standard.
 
-.. introduce talons, etc.
-.. also create a separate FAQ
-
 
 First Steps
 -----------
@@ -76,6 +73,12 @@ query using the above technique. The team has worked hard to optimize
 the docstrings for readability, so that you can quickly scan them and find
 what you need.
 
+.. note::
+
+    `bpython <http://bpython-interpreter.org/>`_ is another super-
+    powered REPL that is good to have in your toolbox when
+    exploring a new library.
+
 
 Hosting Your App
 ----------------
@@ -662,22 +665,17 @@ information on using this feature to DRY up your code:
 What Now?
 ---------
 
+Our friendly community is available to answer your questions and help you
+work through sticky problems. See also: :ref:`Getting Help <help>`.
+
 As mentioned previously, Falcon's docstrings are quite extensive, and so you
 can learn a lot just by poking around Falcon's modules from a Python REPL,
-such as `IPython <http://ipython.org/>`_.
+such as `IPython <http://ipython.org/>`_ or
+`bpython <http://bpython-interpreter.org/>`_.
 
 Also, don't be shy about pulling up Falcon's source code on GitHub or in your
 favorite text editor. The team has tried to make the code as straightforward
 and readable as possible; where other documentation may fall short, the code basically
 "can't be wrong."
 
-As you play around with Falcon and become more familiar with it, please join
-the **#falconframework** IRC channel on
-`Freenode <https://en.wikipedia.org/wiki/Freenode>`_. It's a great place to
-ask questions, share ideas, and get the scoop on updates to the Falcon
-web framework itself.
 
-Finally, if you run into something that is harder to use than it should be,
-or you find that something is slow or completely broken, please let the crew
-know in **#falconframework** and/or by
-`submitting an issue <https://github.com/racker/falcon/issues>`_.