Fixed deis#49 -- make module docstring into reST, everyone's happy.

api/urls.py

@@ -6,11 +6,13 @@
 
 .. http:get:: /api/keys/(string:id)/
 
-  Retrieve a :class:`~api.models.Key` by its id.
+  Retrieve a :class:`~api.models.Key` by its `id`.
 
 .. http:delete:: /api/keys/(string:id)/
 
-  Delete a :class:`~api.models.Key` by its id.
+  Destroy a :class:`~api.models.Key` by its `id`.
+
+  See also :meth:`KeyViewSet.destroy() <api.views.KeyViewSet.destroy>`
 
 .. http:get:: /api/keys/
 
@@ -20,21 +22,23 @@
 
   Create a new :class:`~api.models.Key`.
 
+  See also :meth:`KeyViewSet.post_save() <api.views.KeyViewSet.post_save>`
+
 
 Providers
 =========
 
 .. http:get:: /api/providers/(string:id)/
 
-  Retrieve a :class:`~api.models.Provider` by its id.
+  Retrieve a :class:`~api.models.Provider` by its `id`.
 
 .. http:patch:: /api/providers/(string:id)/
 
   Update parts of a :class:`~api.models.Provider`.
 
 .. http:delete:: /api/providers/(string:id)/
 
-  Delete a :class:`~api.models.Provider` by its id.
+  Destroy a :class:`~api.models.Provider` by its `id`.
 
 .. http:get:: /api/providers/
 
@@ -50,15 +54,15 @@
 
 .. http:get:: /api/flavors/(string:id)/
 
-  Retrieve a :class:`~api.models.Flavor` by its id.
+  Retrieve a :class:`~api.models.Flavor` by its `id`.
 
 .. http:patch:: /api/flavors/(string:id)/
 
   Update parts of a :class:`~api.models.Flavor`.
 
 .. http:delete:: /api/flavors/(string:id)/
 
-  Delete a :class:`~api.models.Flavor` by its id.
+  Destroy a :class:`~api.models.Flavor` by its `id`.
 
 .. http:get:: /api/flavors/
 
@@ -68,17 +72,19 @@
 
   Create a new :class:`~api.models.Flavor`.
 
+  See also :meth:`FlavorViewSet.create() <api.views.FlavorViewSet.create>`
+
 
 Formations
 ==========
 
 .. http:get:: /api/formations/(string:id)/
 
-  Retrieve a :class:`~api.models.Formation` by its id.
+  Retrieve a :class:`~api.models.Formation` by its `id`.
 
 .. http:delete:: /api/formations/(string:id)/
 
-  Delete a :class:`~api.models.Formation` by its id.
+  Destroy a :class:`~api.models.Formation` by its `id`.
 
 .. http:get:: /api/formations/
 
@@ -88,20 +94,25 @@
 
   Create a new :class:`~api.models.Formation`.
 
+  See also
+  :meth:`FormationViewSet.create() <api.views.FormationViewSet.create>` and
+  :meth:`FormationViewSet.post_save() <api.views.FormationViewSet.post_save>`
+
+
 Infrastructure
 --------------
 
 .. http:get:: /api/formations/(string:id)/layers/(string:id)/
 
-  Retrieve a :class:`~api.models.Layer` by its id.
+  Retrieve a :class:`~api.models.Layer` by its `id`.
 
 .. http:patch:: /api/formations/(string:id)/layers/(string:id)/
 
   Update parts of a :class:`~api.models.Layer`.
 
 .. http:delete:: /api/formations/(string:id)/layers/(string:id)/
 
-  Delete a :class:`~api.models.Layer` by its id.
+  Destroy a :class:`~api.models.Layer` by its `id`.
 
 .. http:get:: /api/formations/(string:id)/layers/
 
@@ -113,11 +124,11 @@
 
 .. http:get:: /api/formations/(string:id)/nodes/(string:id)/
 
-  Retrieve a :class:`~api.models.Node` by its id.
+  Retrieve a :class:`~api.models.Node` by its `id`.
 
 .. http:delete:: /api/formations/(string:id)/nodes/(string:id)/
 
-  Delete a :class:`~api.models.Node` by its id.
+  Destroy a :class:`~api.models.Node` by its `id`.
 
 .. http:get:: /api/formations/(string:id)/nodes/
 
@@ -141,15 +152,15 @@
 
 .. http:get:: /api/formations/(string:id)/builds/(string:uuid)/
 
-  Retrieve a :class:`~api.models.Build` by its uuid.
+  Retrieve a :class:`~api.models.Build` by its `uuid`.
 
 .. http:post:: /api/formations/(string:id)/builds/
 
   Create a new :class:`~api.models.Build`.
 
 .. http:get:: /api/formations/(string:id)/releases/(int:version)/
 
-  Retrieve a :class:`~api.models.Release` by its version.
+  Retrieve a :class:`~api.models.Release` by its `version`.
 
 .. http:get:: /api/formations/(string:id)/releases/
 
@@ -160,23 +171,28 @@
 
 .. http:post:: /api/formations/(string:id)/scale/layers/
 
-    scale_layers
+  See also
+  :meth:`FormationViewSet.scale_layers() <api.views.FormationViewSet.scale_layers>`
 
 .. http:post:: /api/formations/(string:id)/scale/containers/
 
-    scale_containers
+  See also
+  :meth:`FormationViewSet.scale_containers() <api.views.FormationViewSet.scale_containers>`
 
 .. http:post:: /api/formations/(string:id)/balance/
 
-    balance
+  See also
+  :meth:`FormationViewSet.balance() <api.views.FormationViewSet.balance>`
 
 .. http:post:: /api/formations/(string:id)/calculate/
 
-    calculate
+  See also
+  :meth:`FormatinViewSet.calculate() <api.views.FormationViewSet.calculate>`
 
 .. http:post:: /api/formations/(string:id)/converge/
 
-    converge
+  See also
+  :meth:`FormationViewSet.converge() <api.views.FormationViewSet.converge>`
 
 
 Auth

client/deis.py

@@ -4,11 +4,13 @@
 
 Usage: deis <command> [--formation <formation>] [<args>...]
 
+::
+
   register      register a new user with a controller
   login         login to a controller
   logout        logout from the current controller
 
-Shortcut commands:
+Shortcut commands::
 
   create        create a new container formation
   info          print a representation of the formation
@@ -17,7 +19,7 @@
   calculate     recalculate and update the formation databag
   destroy       destroy a container formation
 
-Subcommands, use `deis help [subcommand]` to learn more:
+Subcommands, use `deis help [subcommand]` to learn more::
 
   formations    manage container formations
   layers        manage layers of nodes

docs/api/index.rst

@@ -13,6 +13,8 @@ API Reference
 .. toctree::
     :maxdepth: 1
 
+    rest
+
     api.fields
     api.models
     api.routers
@@ -30,8 +32,6 @@ API Reference
     celerytasks.mock
     celerytasks.util
 
-    client
-
     web.models
     web.urls
     web.views

docs/api/rest.rst

@@ -0,0 +1,7 @@
+========
+REST API
+========
+
+.. _rest:
+
+.. automodule:: api.urls

docs/commandline/index.rst

@@ -7,4 +7,4 @@
 CLI cheatsheet
 ==============
 
-**Coming soon...**
+.. automodule:: client.deis