diff options
author | Jason R. Coombs <jaraco@jaraco.com> | 2016-12-24 22:07:07 -0500 |
---|---|---|
committer | Jason R. Coombs <jaraco@jaraco.com> | 2016-12-24 22:07:07 -0500 |
commit | 6c2256c9d11b1c435ce416539dc268d79eb80967 (patch) | |
tree | 208f3db4427a0cb8db97ff7b7814c43e2e6795be | |
parent | 99132307f646e87c5a50bd243114af5058fb152f (diff) | |
download | cherrypy-git-6c2256c9d11b1c435ce416539dc268d79eb80967.tar.gz |
Move much of the readme into the documentation and link from a more concise readme.
-rw-r--r-- | README.rst | 116 | ||||
-rw-r--r-- | docs/development.rst | 20 | ||||
-rw-r--r-- | docs/index.rst | 24 |
3 files changed, 47 insertions, 113 deletions
@@ -1,15 +1,12 @@ -CherryPy -======== - |CherryPy Build Status| |Codacy Badge| -Welcome to the GitHub-repository of `CherryPy <http://cherrypy.org/>`__! +Welcome to the GitHub repository of `CherryPy <http://cherrypy.org/>`_! CherryPy is a pythonic, object-oriented HTTP framework. 1. It allows building web applications in much the same way one would build any other object-oriented program. -2. This results in less and more readable code being developed faster. +2. This design results in less and more readable code being developed faster. It's all just properties and methods. 3. It is now more than ten years old and has proven fast and very stable. @@ -34,113 +31,28 @@ And it continues to work that intuitively when systems grow, allowing for the Python object model to be dynamically presented as a web site and/or API. -Table of contents ------------------ - -.. raw:: html - - <!-- START doctoc generated TOC please keep comment here to allow auto update --> - -.. raw:: html - - <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> - -- `Help <#help>`__ - - - `I don't understand the - documentation <#i-dont-understand-the-documentation>`__ - - `I have a question <#i-have-a-question>`__ - - `I have found a bug <#i-have-found-a-bug>`__ - - `I have a feature request <#i-have-a-feature-request>`__ - - `I want to discuss CherryPy, reach out to developers or CherryPy - users - users <#i-want-to-discuss-cherrypy-reach-out-to-developers-or-cherrypy-users>`__ - -- `Documentation <#documentation>`__ -- `Installation <#installation>`__ -- `Pip <#pip>`__ -- `Source <#source>`__ -- `Development <#development>`__ -- `Contributing <#contributing>`__ -- `Testing <#testing>`__ - -.. raw:: html - - <!-- END doctoc generated TOC please keep comment here to allow auto update --> - -Help -==== - -What are my options if I feel I need help? - -I don't understand the documentation ------------------------------------- - While CherryPy is one of the easiest and most intuitive frameworks out there, the prerequisite for understanding the `CherryPy -documentation <http://docs.cherrypy.org/en/latest/>`__ is that you have +documentation <http://docs.cherrypy.org/en/latest/>`_ is that you have a general understanding of Python and web development. +Additionally: -So if you have that, and still cannot understand the documentation, it -is probably not your fault. `Please create an -issue <https://github.com/cherrypy/cherrypy/issues/new>`__ in those -cases. - -I have a question ------------------ - -If you have a question and cannot find an answer for it in issues or the -the `documentation <http://docs.cherrypy.org/en/latest/>`__, `please -create an issue <https://github.com/cherrypy/cherrypy/issues/new>`__. - -Questions and their answers have great value for the community, and a -tip is to really put the effort in and write a good explanation, you -will get better and quicker answers. Examples are strongly encouraged. - -I have found a bug ------------------- - -If no one have already, `create an -issue <https://github.com/cherrypy/cherrypy/issues/new>`__. Be sure to -provide ample information, remember that any help won't be better than -your explanation. - -Unless something is very obviously wrong, you are likely to be asked to -provide a working example, displaying the erroneous behaviour. - -Note: While this might feel troublesome, a tip is to always make a -separate example that have the same dependencies as your project. It is -great for troubleshooting those annoying problems where you don't know -if the problem is at your end or the components. Also, you can then -easily fork and provide as an example. You will get answers and -resolutions way quicker. Also, many other open source projects require -it. - -I have a feature request ------------------------- - -`Good stuff! Please create an -issue! <https://github.com/cherrypy/cherrypy/issues/new>`__\ Note: -Features are more likely to be added the more users they seem to -benefit. +- Tutorials are included in the repository: + https://github.com/cherrypy/cherrypy/tree/master/cherrypy/tutorial +- A general wiki at(will be moved to github): + https://bitbucket.org/cherrypy/cherrypy/wiki/Home +- Plugins are described at: http://tools.cherrypy.org/ -I want to discuss CherryPy, reach out to developers or CherryPy users ---------------------------------------------------------------------- +If the docs are insufficient to address your needs, the CherryPy +community has several `avenues for support +<https://docs.cherrypy.org/en/latest/support>`_. -`The gitter page <https://gitter.im/cherrypy/cherrypy>`__ is good for -when you want to talk, but doesn't feel that the discussion has to be -indexed for posterity. Documentation ============= - The official user documentation of CherryPy is at: http://docs.cherrypy.org/en/latest/ -- Tutorials are included in the repository: - https://github.com/cherrypy/cherrypy/tree/master/cherrypy/tutorial -- A general wiki at(will be moved to github): - https://bitbucket.org/cherrypy/cherrypy/wiki/Home -- Plugins are described at: http://tools.cherrypy.org/ Installation ============ @@ -177,9 +89,9 @@ Contributing ------------ Please follow the `contribution -guidelines <https://github.com/cherrypy/cherrypy/blob/master/CONTRIBUTING.txt>`__. +guidelines <https://github.com/cherrypy/cherrypy/blob/master/CONTRIBUTING.txt>`_. And by all means, `absorb the Zen of -CherryPy <https://bitbucket.org/cherrypy/cherrypy/wiki/ZenOfCherryPy>`__. +CherryPy <https://bitbucket.org/cherrypy/cherrypy/wiki/ZenOfCherryPy>`_. Testing ------- diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 00000000..c7597b51 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,20 @@ +Testing +------- + +- To run the regression tests, first install tox: + + .. code:: sh + + pip install tox + + then run it + + .. code:: sh + + tox + +- To run individual tests type: + + .. code:: sh + + tox -- -k test_foo diff --git a/docs/index.rst b/docs/index.rst index 0ccc48aa..30de9207 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ - + CherryPy - A Minimalist Python Web Framework ============================================ @@ -13,17 +13,19 @@ CherryPy - A Minimalist Python Web Framework config.rst extend.rst deploy.rst + support.rst contribute.rst + development.rst glossary.rst `CherryPy <http://www.cherrypy.org>`_ is a pythonic, object-oriented web framework. -CherryPy allows developers to build web applications in much the -same way they would build any other object-oriented Python program. +CherryPy allows developers to build web applications in much the +same way they would build any other object-oriented Python program. This results in smaller source code developed in less time. -CherryPy is now more than ten years old and it is has proven to -be fast and reliable. It is being used in production by many +CherryPy is now more than ten years old and it is has proven to +be fast and reliable. It is being used in production by many sites, from the simplest to the most demanding. A CherryPy application typically looks like this: @@ -31,7 +33,7 @@ A CherryPy application typically looks like this: .. code-block:: python import cherrypy - + class HelloWorld(object): @cherrypy.expose def index(self): @@ -41,11 +43,11 @@ A CherryPy application typically looks like this: In order to make the most of CherryPy, you should start with the :ref:`tutorials <tutorials>` that will lead you through the most common -aspects of the framework. Once done, you will probably want to -browse through the :ref:`basics <basics>` and :ref:`advanced <advanced>` -sections that will demonstrate how to implement certain operations. -Finally, you will want to carefully read the configuration and -:ref:`extend <extend>` sections that go in-depth regarding the +aspects of the framework. Once done, you will probably want to +browse through the :ref:`basics <basics>` and :ref:`advanced <advanced>` +sections that will demonstrate how to implement certain operations. +Finally, you will want to carefully read the configuration and +:ref:`extend <extend>` sections that go in-depth regarding the powerful features provided by the framework. Above all, have fun with your application! |