diff --git a/doc/web/api.rst b/doc/web/api.rst index 13df6a40f..ef8e47088 100644 --- a/doc/web/api.rst +++ b/doc/web/api.rst @@ -13,6 +13,10 @@ Web Support API Initialize attributes. +.. method:: build() + + Build the data used by the web support package. + .. method:: get_document(docname) Retrieve the context dictionary corresponding to the *docname*. diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst index 94dfb576a..d519323eb 100644 --- a/doc/web/quickstart.rst +++ b/doc/web/quickstart.rst @@ -3,6 +3,9 @@ Web Support Quick Start ======================= +Getting Started +~~~~~~~~~~~~~~~ + To use the :ref:`websupportapi` in your application you must import the :class:`~sphinx.websupport.api.WebSupport` object:: @@ -13,22 +16,48 @@ object. You will then need to provide some information about your environment:: support.init(srcdir='/path/to/rst/sources/', - outdir='/path/to/build/outdir') + outdir='/path/to/build/outdir', + search='xapian') -You only need to provide a srcdir if you are building documentation:: +Note: You only need to provide a srcdir if you are building documentation. + +Building Documentation Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to use the web support package in a webapp, you will need to +build the data it uses. This data includes document data used to display +documentation and search indexes. To build this data, call the build method:: support.build() This will create the data the web support package needs and place -it in *outdir*. You can then access this data by calling the -get_document(docname) method. For example, to retrieve the "contents" -document, do this:: +it in *outdir*. + +Accessing Document Data +~~~~~~~~~~~~~~~~~~~~~~~ + +To access document data, call the get_document(docname) method. For example, +to retrieve the "contents" document, do this:: contents_doc = support.get_document('contents') This will return a dictionary containing the context you need to render a document. +Performing Searches +~~~~~~~~~~~~~~~~~~~ + +To perform a search, call the get_search_results(q) method, with *q* being +the string to be searched for:: + + q = request.GET['q'] + search_doc = support.get_search_results(q) + +This will return a dictionary in the same format as get_document() returns. + +Full Example +~~~~~~~~~~~~ + A more useful example, in the form of a `Flask `_ application is:: @@ -44,6 +73,11 @@ application is:: document = support.get_document(docname) return render_template('doc.html', document=document) + @app.route('/docs/search') + def search(): + document = support.get_search_results(request.args.get('q', '')) + return render_template('doc.html', document=document) + In the previous example the doc.html template would look something like this:: @@ -69,9 +103,18 @@ like this:: {% endblock %} + {% block relbar %} + {{ document.relbar|safe }} + {% endblock %} + {% block body %} {{ document.body|safe }} {% endblock %} {% block sidebar %} + {{ document.sidebar|safe }} {% endblock %} + + {% block relbar %} + {{ document.relbar|safe }} + {% endblock %} \ No newline at end of file