diff --git a/docs/source/index.rst b/docs/source/index.rst index fab236b..c6f7f1f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -85,6 +85,7 @@ User Guides .. toctree:: :maxdepth: 2 + quickstart tour api diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000..126e711 --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,49 @@ +Quick Start +=========== + +This section of the documentation exists to provide an introduction to the Responder interface, +as well as educate the user on basic functionality. + + +Declare a Web Service +--------------------- + +The first thing you need to do is declare a web service:: + + import responder + + api = responder.API() + +Hello World! +------------ + +Then, you can add a view / route to it. + +Here, we'll make the root URL say "hello world!":: + + @api.route("/") + def hello_world(req, resp): + resp.text = "hello, world!" + +Run the Server +-------------- + +Next, we can run our web service easily, with ``api.run()``:: + + api.run() + +This will spin up a production web server on port ``5042``, ready for incoming HTTP requests. + +Note: you can pass ``port=5000`` if you want to customize the port. The ``PORT`` environment variable for established web service providers (e.g. Heroku) will automatically be honored. + + +Accept Route Arguments +---------------------- + +If you want dynamic URLs, you can use Python's familiar *f-string syntax* to declare variables in your routes:: + +@api.route("/hello/{who}") +def hello_to(req, resp, *, who): + resp.text = f"hello, {who}!" + +A ``GET`` request to ``/hello/brettcannon`` will result in a response of ``hello, brettcannon!``.