From 547c944bb9c4eeb4b32458cce8fc50f6988b64b5 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Tue, 25 Mar 2014 22:26:16 -0300 Subject: [PATCH] switched to flask theme --- .gitmodules | 3 ++ doc/_themes/flask-sphinx-themes | 1 + doc/client/index.rst | 79 +++++++++++++++++++++++++++++++++ doc/client/users_and_tokens.rst | 21 +++++++++ doc/conf.py | 28 ++++++------ 5 files changed, 119 insertions(+), 13 deletions(-) create mode 100644 .gitmodules create mode 160000 doc/_themes/flask-sphinx-themes create mode 100644 doc/client/index.rst create mode 100644 doc/client/users_and_tokens.rst diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..0fb1808 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "doc/_themes/flask-sphinx-themes"] + path = doc/_themes/flask-sphinx-themes + url = https://github.com/mitsuhiko/flask-sphinx-themes.git diff --git a/doc/_themes/flask-sphinx-themes b/doc/_themes/flask-sphinx-themes new file mode 160000 index 0000000..1cc4468 --- /dev/null +++ b/doc/_themes/flask-sphinx-themes @@ -0,0 +1 @@ +Subproject commit 1cc44686f0f9dad27cce2c9d16cf42f97bc87dbd diff --git a/doc/client/index.rst b/doc/client/index.rst new file mode 100644 index 0000000..079dc30 --- /dev/null +++ b/doc/client/index.rst @@ -0,0 +1,79 @@ +About the API +============== + +A few things you must know before diving into the API: + +Everything is JSON +------------------- + +Every request should have a JSON payload; anything else will be refused and +return a 400 status. For example: + +.. sourcecode:: http + + POST /randomendpoint + Host: example.com + Accept: text/html + Content-Type: application/x-www-form-urlencoded + + field1=value&field2=value + +The response will always be: + +.. sourcecode:: http + + HTTP/1.1 400 Bad Request + Content-Type: text/json + + { "status": "ERROR", "message": "Request MUST be in JSON format" } + +If instead you do a proper JSON request with: + +.. sourcecode:: http + + POST /randomendpoint + Host: example.com + Content-type: text/json + + { "field1": "value", "field2": "value" } + +Then everything would go fine. + +Standard responses +------------------- + +Responses will always have a ``status`` parameter with the result of the +operation -- more fields may be also returned, depending on the request. + +Successful requests with have the value ``OK`` for ``status`` -- and, again, +more fields may be returned in most cases. Also, the HTTP status code will +**always** be 200. + +In case of failure, ``status`` will have the text ``ERROR`` (in all caps) and +a ``message`` field will have the reason for the error -- and, as success, it +may contain more fields with information about the error. For different errors +in the operation there will be a different HTTP status. We tried as hard as +possible to give each error a meaningful HTTP status, even if this sometimes +wouldn't make much sense -- for example, if you try to change the ownership of +a group and the group doesn't exist, you'll get a 404 status; if the new owner +doesn't exist, instead of a proper 404, we will return a 412 status, not +because there is a precondition error in the headers, but because we need +a different code to point that the new user does not exist. + +Redirects +---------- + +All URLs must end with "/"; if you forget to add them in the URL, you'll +receive a redirect to the path with "/". + +API +---- + +.. toctree:: + :maxdepth: 2 + + users_and_tokens + +.. autoflask:: luncho.server:app + :blueprints: token, users + :undoc-endpoints: static diff --git a/doc/client/users_and_tokens.rst b/doc/client/users_and_tokens.rst new file mode 100644 index 0000000..2cf65a7 --- /dev/null +++ b/doc/client/users_and_tokens.rst @@ -0,0 +1,21 @@ +Users and Tokens +================= + +Token +------ + +All requests require an access token to be valid. The token is valid for a +whole day and, unless you don't have the access token or it expired, you +should use this request to get a valid token: + +.. autoflask:: luncho.server:app + :blueprints: token + :undoc-endpoints: static + + +Users +------ + +.. autoflask:: luncho.server:app + :blueprints: users + :undoc-endpoints: static diff --git a/doc/conf.py b/doc/conf.py index 3365bb7..f2766c2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -19,6 +19,7 @@ import os # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('..')) +sys.path.append(os.path.abspath('_themes/flask-sphinx-themes')) # -- General configuration ------------------------------------------------ @@ -103,7 +104,8 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +#html_theme = 'default' +html_theme = 'flask' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -111,7 +113,7 @@ html_theme = 'default' #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = ['_themes/flask-sphinx-themes/'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -187,22 +189,22 @@ htmlhelp_basename = 'Luncho-odoc' # -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', -# Additional stuff for the LaTeX preamble. -#'preamble': '', + # Additional stuff for the LaTeX preamble. + #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ('index', 'Luncho-o.tex', u'Luncho-o Documentation', - u'Julio Biason', 'manual'), + ('index', 'Luncho-o.tex', u'Luncho-o Documentation', + u'Julio Biason', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -245,9 +247,9 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'Luncho-o', u'Luncho-o Documentation', - u'Julio Biason', 'Luncho-o', 'One line description of project.', - 'Miscellaneous'), + ('index', 'Luncho-o', u'Luncho-o Documentation', + u'Julio Biason', 'Luncho-o', 'Lunch for groups.', + 'Miscellaneous'), ] # Documents to append as an appendix to all manuals.