openstack/deb-python-falcon
Code Issues Proposed changes

Doctor the docs (#882)

Browse Source 
* doc(install): Reconcile install.rst and README.rst

* doc: Bump version string to 1.1

* doc: Add "Who's Using Falcon" section to index.rst, README.rst

* doc: Update mailing list, IRC info

Modify mailing list to point to the Google group, and link to
an online IRC client instead of simply bolding #falconframework.

* doc: Correct docs path in CONTRIBUTING.md

* doc(install): Update GH URL
This commit is contained in:
Kurt Griffiths
2016-08-31 08:35:33 -06:00
committed by John Vrbanac
parent e95eb64cd0
commit f93ffb149e
8 changed files with 190 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
CONTRIBUTING.md
View File

@@ -6,28 +6,26 @@ on GitHub to your personal account and then clone the fork into your
development environment.
Kurt Griffiths (**kgriffs** on IRC and Twitter) is the original creator of the
Falcon framework, and currently co-maintains the project along with John Vrbanac
(**jvrbanac** on IRC and Twitter). Falcon is developed by a growing
Falcon framework, and currently co-maintains the project along with John Vrbanac (**jvrbanac** on IRC and Twitter). Falcon is developed by a growing
community of users and contributors just like you.
Please don't hesitate to reach out if you have any questions, or just need a
little help getting started. You can find us in
the **#falconframework** IRC channel on [Freenode][freenode]. It's the best way to discuss ideas, ask
questions, and generally stay in touch with fellow contributors.
the [#falconframework][irc-channel] IRC channel on [Freenode][freenode]. It's the best way to discuss ideas, ask questions, and generally stay in touch with fellow contributors.
Please note that all contributors and maintainers of this project are subject to our [Code of Conduct][coc].
### Mailing List
### Discussion Group
The Falcon community maintains a mailing list that you can use to share your ideas and ask questions about the framework. To join the list, simply send an email to [<users-join@mail.falconframework.org>][ml-join] (the subject and body will be ignored). You’ll receive a reply asking you to confirm the request.
The Falcon community maintains a discussion group that you can use to
share your ideas and ask questions about the framework. To join the
discussion, please visit https://groups.google.com/d/forum/falconframework.
Per our [Code of Conduct][coc], we expect everyone who participates on the mailing list to act professionally, and lead by example in encouraging constructive discussions. Each individual in the community is responsible for creating a positive, constructive, and productive culture.
[Discussions are archived][ml-archive] for future reference.
Per our [Code of Conduct][coc], we expect everyone who participates in community discussions to act professionally, and lead by example in encouraging constructive discussions. Each individual in the community is responsible for creating a positive, constructive, and productive culture.
### Pull Requests
Before submitting a pull request, please ensure you have added or updated tests as appropriate, and that all existing tests still pass with your changes on both Python 2 and Python 3. Please also ensure that your coding style follows PEP 8 and doesn't cause pyflakes to complain.
Before submitting a pull request, please ensure you have added or updated tests as appropriate, and that all existing tests still pass with your changes on both Python 2 and Python 3. Please also ensure that your coding style follows PEP 8.
You can check all this by running the following from within the falcon project directory (requires Python 2.7 and Python 3.5 to be installed on your system):
@@ -69,13 +67,13 @@ builds the documentation correctly:
$ tox -e docs
# OS X
$ open doc/_build/html/index.html
$ open docs/_build/html/index.html
# Gnome
$ gnome-open doc/_build/html/index.html
$ gnome-open docs/_build/html/index.html
# Generic X Windows
$ xdg-open doc/_build/html/index.html
$ xdg-open docs/_build/html/index.html
```
### Code style rules
@@ -154,5 +152,6 @@ The footer should contain any information about **Breaking Changes** and is also
[rtd]: https://falcon.readthedocs.io
[coc]: https://github.com/falconry/falcon/blob/master/CODEOFCONDUCT.md
[freenode]: https://www.freenode.net/
[irc-channel]: https://kiwiirc.com/client/irc.freenode.net/?#falconframework
[ml-join]: mailto:users-join@mail.falconframework.org?subject=join
[ml-archive]: https://mail.falconframework.org/archives/list/users@mail.falconframework.org/

117
README.rst
View File

@@ -19,7 +19,6 @@ Quick Links
* `Subscribe to the community mailing list <https://falcon.readthedocs.io/en/stable/community/help.html#mailing-list>`__.
* `Hang out in #falconframework on freenode <https://kiwiirc.com/client/irc.freenode.net/?#falconframework>`__.
Design Goals
------------
@@ -41,7 +40,6 @@ mix and match your own favorite libraries. Falcon apps work with
any WSGI server, and run great under `CPython 2.6-2.7, PyPy, Jython 2.7,
and CPython 3.3-3.5 <https://travis-ci.org/falconry/falcon>`__.
Features
--------
@@ -57,6 +55,31 @@ Features
- CPython 2.6-2.7, PyPy, Jython 2.7, and CPython 3.3-3.5 support
- ~20% speed boost when Cython is available
Who's Using Falcon?
-------------------
Falcon is used around the world by a growing number of organizations,
including:
- 7ideas
- Cronitor
- EMC
- Hurricane Electric
- Leadpages
- OpenStack
- Rackspace
- Shiftgig
- tempfil.es
- Opera Software
If you are using the Falcon framework for a community or commercial
project, please consider adding your information to our wiki under
`Who's Using Falcon? <https://github.com/falconry/falcon/wiki/Who's-using-Falcon%3F>`_
You might also like to view our
`Add-on Catalog <https://github.com/falconry/falcon/wiki/Add-on-Catalog>`_,
where you can find a list of add-ons maintained by the community.
Installation
------------
@@ -122,31 +145,70 @@ these issues by setting additional Clang C compiler flags as follows:
$ export CFLAGS="-Qunused-arguments -Wno-unused-function"
Dependencies
------------
^^^^^^^^^^^^
Falcon depends on six and `python-mimeparse`. `python-mimeparse` is a
Falcon depends on `six` and `python-mimeparse`. `python-mimeparse` is a
better-maintained fork of the similarly named `mimeparse` project.
Normally the correct package will be selected by Falcon's ``setup.py``.
However, if you are using an alternate strategy to manage dependencies,
please take care to install the correct package in order to avoid
errors.
Tests
-----
WSGI Server
-----------
Falcon speaks WSGI, and so in order to serve a Falcon app, you will
need a WSGI server. Gunicorn and uWSGI are some of the more popular
ones out there, but anything that can load a WSGI app will do.
.. code:: bash
$ pip install -r tools/test-requires
$ pip install nose && nosetests
$ pip install [gunicorn|uwsgi]
To run the default set of tests:
Source Code
-----------
Falcon `lives on GitHub <https://github.com/falconry/falcon>`_, making the
code easy to browse, download, fork, etc. Pull requests are always welcome! Also,
please remember to star the project if it makes you happy. :)
Once you have cloned the repo or downloaded a tarball from GitHub, you
can install Falcon like this:
.. code:: bash
$ cd falcon
$ pip install .
Or, if you want to edit the code, first fork the main repo, clone the fork
to your desktop, and then run the following to install it using symbolic
linking, so that when you change your code, the changes will be automagically
available to your app without having to reinstall the package:
.. code:: bash
$ cd falcon
$ pip install -e .
You can manually test changes to the Falcon framework by switching to the
directory of the cloned repo and then running pytest:
.. code:: bash
$ cd falcon
$ pip install -r tools/test-requires
$ pytest tests
Or, to run the default set of tests:
.. code:: bash
$ pip install tox && tox
See also the `tox.ini <https://github.com/falconry/falcon/blob/master/tox.ini>`_
file for a full list of available environments.
Read the docs
-------------
@@ -163,10 +225,13 @@ You can build the same docs locally as follows:
$ pip install tox && tox -e docs
Once the docs have been built, you can view them by opening the following
index page in your browser::
index page in your browser. On OS X it's as simple as::
./_build/html/index.html
$ open docs/_build/html/index.html
Or on Linux:
$ xdg-open docs/_build/html/index.html
Getting started
---------------
@@ -447,27 +512,21 @@ bodies.
Community
---------
The Falcon community maintains a mailing list that you can use to share
your ideas and ask questions about the framework. We use the appropriately
minimalistic `Librelist <http://librelist.com/>`_ to host the discussions.
The Falcon community maintains a discussion group that you can use to
share your ideas and ask questions about the framework. To join the
discussion, please visit https://groups.google.com/d/forum/falconframework.
To join the mailing list, simply send your first email to falcon@librelist.com!
This will automatically subscribe you to the mailing list *and* sends your email
along to the rest of the subscribers. For more information about managing your
subscription, check out the
`Librelist help page <http://librelist.com/help.html>`_.
We expect everyone who participates on the mailing list to act
Per our
`Code of Conduct <https://github.com/falconry/falcon/blob/master/CODEOFCONDUCT.md>`_,
we expect everyone who participates in community discussions to act
professionally, and lead by example in encouraging constructive
discussions. Each individual in the community is responsible for
creating a positive, constructive, and productive culture. See also
the `Falcon Code of Conduct <https://github.com/falconry/falcon/blob/master/CODEOFCONDUCT.md>`__
creating a positive, constructive, and productive culture.
`Discussions are archived <http://librelist.com/browser/falcon>`__ for
posterity.
We also hang out in `#falconframework <https://kiwiirc.com/client/irc.freenode.net/?#falconframework>`__ on freenode, where everyone is
always welcome to ask questions and share ideas.
We also hang out in
`#falconframework <https://kiwiirc.com/client/irc.freenode.net/?#falconframework>`_
on freenode, where everyone is always welcome to ask questions and share
ideas.
Contributing
------------

6
docs/community/contribute.rst
View File

@@ -15,9 +15,9 @@ community of users and contributors just like you.
Please don't hesitate to reach out if you have any questions, or just need a
little help getting started. You can find us in
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.
`#falconframework <https://kiwiirc.com/client/irc.freenode.net/?#falconframework>`_
on `Freenode <https://www.freenode.net/>`_. It's the best way to discuss ideas,
ask questions, and generally stay in touch with fellow contributors.
Please check out our
`Contributor's Guide <https://github.com/falconry/falcon/blob/master/CONTRIBUTING.md>`_

25
docs/community/help.rst
View File

@@ -13,26 +13,21 @@ IRC
---
Chat with fellow community members in the official Falcon IRC channel. It's a
great place to ask questions and share your ideas. You can find us in
**#falconframework** on `Freenode <https://en.wikipedia.org/wiki/Freenode>`_.
`#falconframework <https://kiwiirc.com/client/irc.freenode.net/?#falconframework>`_
on `Freenode <https://en.wikipedia.org/wiki/Freenode>`_.
Mailing List
------------
The Falcon community maintains a mailing list that you can use to share
your ideas and ask questions about the framework. To join the list, simply send
an email to
`users-join@mail.falconframework.org <mailto:users-join@mail.falconframework.org?subject=join>`_
(the subject and body will be ignored). You'll receive a reply asking you to
confirm the request.
Discussion Group
----------------
The Falcon community maintains a discussion group that you can use to
share your ideas and ask questions about the framework. To join the
discussion, please visit https://groups.google.com/d/forum/falconframework.
Per our
`Code of Conduct <https://github.com/falconry/falcon/blob/master/CODEOFCONDUCT.md>`_,
we expect everyone who participates on the mailing list to act
we expect everyone who participates in community discussions to act
professionally, and lead by example in encouraging constructive
discussions. Each individual in the community is responsible for creating
a positive, constructive, and productive culture.
`Discussions are archived <https://mail.falconframework.org/archives/list/users@mail.falconframework.org/>`_
for future reference.
discussions. Each individual in the community is responsible for
creating a positive, constructive, and productive culture.
Submit Issues
-------------

4
docs/conf.py
View File

@@ -62,9 +62,9 @@ copyright = u'2016, Rackspace Hosting et al. (as noted in the source code)'
# built documents.
#
# The short X.Y version.
version = '1.0'
version = '1.1'
# The full version, including alpha/beta/rc tags.
release = '1.0.0'
release = '1.1.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

26
docs/index.rst
View File

@@ -47,7 +47,6 @@ documentation. It basically can't be wrong."
"What other framework has integrated support for '786 TRY IT NOW' ?"
Features
--------
@@ -66,6 +65,31 @@ Falcon tries to do as little as possible while remaining highly effective.
- Supports Python 2.6, 2.7, 3.3, 3.4 and 3.5
- Compatible with PyPy and Jython
Who's Using Falcon?
-------------------
Falcon is used around the world by a growing number of organizations,
including:
- 7ideas
- Cronitor
- EMC
- Hurricane Electric
- Leadpages
- OpenStack
- Rackspace
- Shiftgig
- tempfil.es
- Opera Software
If you are using the Falcon framework for a community or commercial
project, please consider adding your information to our wiki under
`Who's Using Falcon? <https://github.com/falconry/falcon/wiki/Who's-using-Falcon%3F>`_
You might also like to view our
`Add-on Catalog <https://github.com/falconry/falcon/wiki/Add-on-Catalog>`_,
where you can find a list of add-ons maintained by the community.
Useful Links
------------

58
docs/user/install.rst
View File

@@ -65,26 +65,33 @@ these issues by setting additional Clang C compiler flags as follows:
$ export CFLAGS="-Qunused-arguments -Wno-unused-function"
Dependencies
------------
Falcon depends on `six` and `python-mimeparse`. `python-mimeparse` is a
better-maintained fork of the similarly named `mimeparse` project.
Normally the correct package will be selected by Falcon's ``setup.py``.
However, if you are using an alternate strategy to manage dependencies,
please take care to install the correct package in order to avoid
errors.
WSGI Server
-----------
Falcon speaks WSGI. If you want to actually serve a Falcon app, you will
want a good WSGI server. Gunicorn and uWSGI are some of the more popular
ones out there, but anything that can load a WSGI app will do. Gevent is
an async library that works well with both Gunicorn and uWSGI.
Falcon speaks WSGI, and so in order to serve a Falcon app, you will
need a WSGI server. Gunicorn and uWSGI are some of the more popular
ones out there, but anything that can load a WSGI app will do.
.. code:: bash
$ pip install gevent [gunicorn|uwsgi]
$ pip install [gunicorn|uwsgi]
Source Code
-----------
Falcon `lives on GitHub <https://github.com/racker/falcon>`_, making the
Falcon `lives on GitHub <https://github.com/falconry/falcon>`_, making the
code easy to browse, download, fork, etc. Pull requests are always welcome! Also,
please remember to star the project if it makes you happy.
please remember to star the project if it makes you happy. :)
Once you have cloned the repo or downloaded a tarball from GitHub, you
can install Falcon like this:
@@ -104,4 +111,37 @@ available to your app without having to reinstall the package:
$ cd falcon
$ pip install -e .
Did we mention we love pull requests? :)
You can manually test changes to the Falcon framework by switching to the
directory of the cloned repo and then running pytest:
.. code:: bash
$ cd falcon
$ pip install -r tools/test-requires
$ pytest tests
Or, to run the default set of tests:
.. code:: bash
$ pip install tox && tox
.. tip::
See also the `tox.ini <https://github.com/falconry/falcon/blob/master/tox.ini>`_
file for a full list of available environments.
Finally, to build Falcon's docs from source, simply run:
.. code:: bash
$ pip install tox && tox -e docs
Once the docs have been built, you can view them by opening the following
index page in your browser. On OS X it's as simple as::
$ open docs/_build/html/index.html
Or on Linux::
$ xdg-open docs/_build/html/index.html

2
docs/user/intro.rst
View File

@@ -32,4 +32,4 @@ Now, if you do make changes to Falcon itself, please consider contributing your
Falcon License
--------------
.. include:: ../../LICENSE
.. include:: ../../LICENSE