Include README.rst into sphinx docs.

plone · Apr 17, 2015 · 00226cb · 00226cb
1 parent 9396236
commit 00226cb
Show file tree

Hide file tree

Showing 4 changed files with 121 additions and 121 deletions.
diff --git a/README.rst b/README.rst
@@ -1,5 +1,3 @@
-.. contents::
-
 Introduction
 ============
 
@@ -14,6 +12,7 @@ Introduction
 
 plone.restapi is a RESTful hypermedia API for Plone.
 
+
 RESTful Hypermedia API
 ----------------------
 
@@ -39,19 +38,25 @@ https://github.com/plone/plone.restapi/milestones
 Live Demo
 =========
 
-http://arcane-sierra-8467.herokuapp.com/Plone/@@json
+Heroku live demo:: http://arcane-sierra-8467.herokuapp.com/Plone/@@json
+
+.. note:: The demo works best with a browser plugin that makes json links clickable in the browser (e.g. https://addons.mozilla.org/de/firefox/addon/jsonview/).
 
 
 Design Decisions
 ================
 
-* RESTful API
-* Hypermedia / HATEOAS / Linked-data
-* Use JSON as main format, support other formats (HTML, XML) later
+* A truly RESTful API (Hypermedia / HATEOAS / Linked-data)
+* JSON is the main target formt, support other formats (HTML, XML) later
 * Use HTTP headers (to set format and versioning, also provide URL-based option to make it easier for people to try it out)
 * Versioning should be included (we will decide later, if we actually want to support multiple versions at the same time)
 * Field names just map over (we will not try to clean up attributes or enforce naming standards like pep8 (e.g. isPrincipiaFoldish -> is_folderish)
 * Dexterity only. We will not put effort into supporting Archetypes.
 
+Software Quality
+================
+
+* 100% Test Coverage
+* 100% PEP8 compliant
 
 .. _`Representational State Transfer`: http://en.wikipedia.org/wiki/Representational_state_transfer
diff --git a/docs/source/alert-noindex.rst b/docs/source/alert-noindex.rst
@@ -2,5 +2,4 @@
    :robots: noindex, nofollow
 
 .. warning::
-   This documentation refers to a feature currently in the planning stage.
-   Any functionality described by this document is not currently available on Plone, and serves only as reference and source for discussion and collaboration about it.
+   plone.restapi ist still in a pre-alpha stage. Any functionality described by this document might not be currently available on Plone, and/or might change significantly in the future.
diff --git a/docs/source/index.old.rst b/docs/source/index.old.rst
@@ -0,0 +1,105 @@
+Design Decisions
+----------------
+
+Preliminary. Those are currently more goals than final design decisions.
+
+- RESTful API
+- Hypermedia / HATEOAS / Linked-data
+- Use JSON as main format
+- Use HTTP headers (to set format and versioning, also provide URL-based option to make it easier for people to try it out)
+- Versioning should be included (we will decide later, if we actually want to support multiple versions at the same time)
+- Field names just map over (we will not try to clean up attributes or enforce naming standards like pep8 (e.g. isPrincipiaFoldish -> is_folderish)
+- Dexterity only. We will not put effort into supporting Archetypes.
+
+
+Process
+-------
+
+We plan to follow the very successful "design & documentation first" approach of plone.api.
+
+1) Design, discussion, and documentation first
+2) Tests and testing infrastructure
+3) Proof-of-concept implementations to verify that our basic design will work
+4) Implementation
+
+Nejc Zupan offered to review our process and provide advice, if necessary.
+
+
+Scope
+-----
+
+Start with a minimal viable API and go on from there (while iterating over the 'Process' steps):
+
+1) Browse as anonymous user (GET ONLY), most basic Plone functionality
+2) Search and other basic Plone functionalities, that do not require authentication
+3) Authentication
+4) Basic CRUD + Workflow
+5) Expose full Plone API
+
+
+Existing Standards
+------------------
+
+Standards that we might take into consideration:
+
+- JSON-LD: http://www.w3.org/TR/json-ld/
+- JSON Schema: http://json-schema.org/
+- Schema.org: http://schema.org/
+- Hydra: http://www.w3.org/ns/hydra/spec/latest/core/
+- Collection+JSON: http://amundsen.com/media-types/collection/
+- Siren: https://github.com/kevinswiber/siren
+
+
+Tools
+-----
+
+- APIary: https://app.apiary.io/plonerestapi
+- Swagger: http://petstore.swagger.wordnik.com/
+
+
+Testing
+-------
+
+- Sphinx-based?
+- Robot-Framework based?
+
+
+Proof of Concept Implementations
+--------------------------------
+
+- ZServer (Support for GET/POST/PUT/DELETE):
+  https://github.com/tisto/plone.app.angularjs/commit/828440770c22991c38d146bfcf0e1c67559f60d9
+- Transformation (Dexerity Object + Behavior -> JSON):
+  https://github.com/tisto/plone.app.angularjs/blob/master/src/plone/app/angularjs/utils.py#L9
+
+
+References
+==========
+
+The design of the API has been influenced by the following resources, books, and projects:
+
+REST in Practice: Hypermedia and Systems Architecture
+
+    by Jim Webber, Savas Parastatidis, Ian S Robinson
+
+RESTful Web APIs
+
+   by Leonard Richardson, Mike Amundsen, Sam Ruby
+
+   O'Reilly Media, 2013
+
+   ISBN 978-1-4493-5806-8
+
+   http://shop.oreilly.com/product/0636920028468.do
+
+REST cookbook
+   By Joshua Thyssen and others
+
+   http://restcookbook.com
+
+Python-EVE
+   A generic RESTful app framework
+
+   by Nicola Iarocci
+
+   http://python-eve.org/
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -3,17 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-+++++++++++++++++++++++++++++
-plone.restapi's documentation
-+++++++++++++++++++++++++++++
+==================================================
+plone.restapi: A RESTful hypermedia API for Plone.
+==================================================
 
 .. include:: /alert-noindex.rst
 
-``plone.restapi`` aims to provide a RESTful API for Plone.
-
-Its main focus in to enable clients (be it other services, Javascript frontends, command line clients or desktop applications, to name a few) to access the content management functionalities offered by Plone.
-
-
 Contents
 ========
 
@@ -37,111 +32,7 @@ Contents
 ..   global-objects
 
 
-Design Decisions
-----------------
-
-Preliminary. Those are currently more goals than final design decisions.
-
-- RESTful API
-- Hypermedia / HATEOAS / Linked-data
-- Use JSON as main format
-- Use HTTP headers (to set format and versioning, also provide URL-based option to make it easier for people to try it out)
-- Versioning should be included (we will decide later, if we actually want to support multiple versions at the same time)
-- Field names just map over (we will not try to clean up attributes or enforce naming standards like pep8 (e.g. isPrincipiaFoldish -> is_folderish)
-- Dexterity only. We will not put effort into supporting Archetypes.
-
-
-Process
--------
-
-We plan to follow the very successful "design & documentation first" approach of plone.api.
-
-1) Design, discussion, and documentation first
-2) Tests and testing infrastructure
-3) Proof-of-concept implementations to verify that our basic design will work
-4) Implementation
-
-Nejc Zupan offered to review our process and provide advice, if necessary.
-
-
-Scope
------
-
-Start with a minimal viable API and go on from there (while iterating over the 'Process' steps):
-
-1) Browse as anonymous user (GET ONLY), most basic Plone functionality
-2) Search and other basic Plone functionalities, that do not require authentication
-3) Authentication
-4) Basic CRUD + Workflow
-5) Expose full Plone API
-
-
-Existing Standards
-------------------
-
-Standards that we might take into consideration:
-
-- JSON-LD: http://www.w3.org/TR/json-ld/
-- JSON Schema: http://json-schema.org/
-- Schema.org: http://schema.org/
-- Hydra: http://www.w3.org/ns/hydra/spec/latest/core/
-- Collection+JSON: http://amundsen.com/media-types/collection/
-- Siren: https://github.com/kevinswiber/siren
-
-
-Tools
------
-
-- APIary: https://app.apiary.io/plonerestapi
-- Swagger: http://petstore.swagger.wordnik.com/
-
-
-Testing
--------
-
-- Sphinx-based?
-- Robot-Framework based?
-
-
-Proof of Concept Implementations
---------------------------------
-
-- ZServer (Support for GET/POST/PUT/DELETE):
-  https://github.com/tisto/plone.app.angularjs/commit/828440770c22991c38d146bfcf0e1c67559f60d9
-- Transformation (Dexerity Object + Behavior -> JSON):
-  https://github.com/tisto/plone.app.angularjs/blob/master/src/plone/app/angularjs/utils.py#L9
-
-
-References
-==========
-
-The design of the API has been influenced by the following resources, books, and projects:
-
-REST in Practice: Hypermedia and Systems Architecture
-
-    by Jim Webber, Savas Parastatidis, Ian S Robinson
-
-RESTful Web APIs
-
-   by Leonard Richardson, Mike Amundsen, Sam Ruby
-
-   O'Reilly Media, 2013
-
-   ISBN 978-1-4493-5806-8
-
-   http://shop.oreilly.com/product/0636920028468.do
-
-REST cookbook
-   By Joshua Thyssen and others
-
-   http://restcookbook.com
-
-Python-EVE
-   A generic RESTful app framework
-
-   by Nicola Iarocci
-
-   http://python-eve.org/
+.. include:: ../../README.rst
 
 
 Indices and tables