Fixed #174 -- updated Sphinx docs to match refactored modules.

deis · Sep 17, 2013 · f6f13b4 · f6f13b4
1 parent cd28ce4
commit f6f13b4
Show file tree

Hide file tree

Showing 25 changed files with 170 additions and 280 deletions.
diff --git a/api/utils.py b/api/utils.py
@@ -61,5 +61,5 @@ def generate_app_name():
         'yachting', 'yardbird', 'yearbook', 'yearling', 'yeomanry', 'yodeling',
         'zaniness', 'zeppelin', 'ziggurat', 'zirconia', 'zoologer', 'zucchini',
     ]
-    return '{}-{}'.format(
+    return "{}-{}".format(
         random.choice(adjectives), random.choice(nouns))
diff --git a/cm/chef.py b/cm/chef.py
@@ -44,8 +44,13 @@
     _valid_pem_path = os.path.join(CHEF_CONFIG_PATH, 'validation.pem')
     CHEF_VALIDATION_KEY = subprocess.check_output(
         ['sudo', '/bin/cat', _valid_pem_path]).strip('\n')
-except Exception as e:
-    raise EnvironmentError('Failed to auto-configure Chef -- {}'.format(e))
+except Exception as err:
+    msg = "Failed to auto-configure Chef -- {}".format(err)
+    if os.environ.get('READTHEDOCS'):
+        # Just print the error if Sphinx is running
+        print(msg)
+    else:
+        raise EnvironmentError(msg)
 
 
 def _get_client():

diff --git a/cm/views.py b/cm/views.py
diff --git a/dev_requirements.txt b/dev_requirements.txt
@@ -22,7 +22,7 @@ docopt==0.6.1
 requests==1.2.3
 
 # Deis documentation requirements
-Sphinx>=1.2b1
+Sphinx>=1.2b2
 smartypants>=1.8.2
 sphinxcontrib-httpdomain>=1.1.9
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -9,6 +9,9 @@ PYTHON        = python
 ZIP           = zip
 BUILDDIR      = _build
 
+READTHEDOCS   = true
+export READTHEDOCS
+
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
 $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)

diff --git a/docs/server/api.ssh.rst b/docs/server/api.ssh.rst
@@ -0,0 +1,14 @@
+:description: Python API Reference for the Deis api.ssh module
+:keywords: deis, api.ssh, python, api
+
+=======
+api.ssh
+=======
+
+.. contents::
+    :local:
+.. currentmodule:: api.ssh
+
+.. automodule:: api.ssh
+    :members:
+    :undoc-members:
diff --git a/docs/server/api.tasks.rst b/docs/server/api.tasks.rst
@@ -0,0 +1,27 @@
+:description: Python API Reference for the Deis api.tasks module
+:keywords: deis, api.tasks, python, api
+
+=========
+api.tasks
+=========
+
+.. contents::
+    :local:
+.. currentmodule:: api.tasks
+
+.. automodule:: api.tasks
+    :members:
+    :undoc-members:
+
+    .. autofunction:: build_layer(layer)
+    .. autofunction:: destroy_layer(layer)
+    .. autofunction:: build_node(node)
+    .. autofunction:: destroy_node(node)
+    .. autofunction:: converge_node(node)
+    .. autofunction:: run_node(node, command)
+    .. autofunction:: build_formation(formation)
+    .. autofunction:: destroy_formation(formation)
+    .. autofunction:: converge_formation(formation)
+    .. autofunction:: build_app(app)
+    .. autofunction:: destroy_app(app)
+    .. autofunction:: converge_controller()
diff --git a/docs/server/celerytasks.azuresms.rst b/docs/server/celerytasks.azuresms.rst
diff --git a/docs/server/celerytasks.chef.rst b/docs/server/celerytasks.chef.rst
diff --git a/docs/server/celerytasks.chef_mock.rst b/docs/server/celerytasks.chef_mock.rst
diff --git a/docs/server/celerytasks.chef_rsa.rst b/docs/server/celerytasks.chef_rsa.rst
diff --git a/docs/server/celerytasks.controller.rst b/docs/server/celerytasks.controller.rst
diff --git a/docs/server/celerytasks.ec2.rst b/docs/server/celerytasks.ec2.rst
diff --git a/docs/server/celerytasks.mock.rst b/docs/server/celerytasks.mock.rst
diff --git a/docs/server/celerytasks.util.rst b/docs/server/celerytasks.util.rst
diff --git a/docs/server/cm.chef.rst b/docs/server/cm.chef.rst
@@ -0,0 +1,14 @@
+:description: Python API Reference for the Deis cm.chef module
+:keywords: deis, cm.chef, python, celery, configuration management, chef, api
+
+=======
+cm.chef
+=======
+
+.. contents::
+    :local:
+.. currentmodule:: cm.chef
+
+.. automodule:: cm.chef
+    :members:
+    :undoc-members:
diff --git a/docs/server/cm.chef_api.rst b/docs/server/cm.chef_api.rst
@@ -0,0 +1,14 @@
+:description: Python API Reference for the Deis cm.chef_api module
+:keywords: deis, cm.chef_api, python, celery, configuration management, chef, api
+
+===========
+cm.chef_api
+===========
+
+.. contents::
+    :local:
+.. currentmodule:: cm.chef_api
+
+.. automodule:: cm.chef_api
+    :members:
+    :undoc-members:
diff --git a/docs/server/cm.chef_rsa.rst b/docs/server/cm.chef_rsa.rst
@@ -0,0 +1,14 @@
+:description: Python API Reference for the Deis cm.chef_rsa module
+:keywords: deis, cm.chef_rsa, python, celery, configuration management, chef, rsa, api
+
+===========
+cm.chef_rsa
+===========
+
+.. contents::
+    :local:
+.. currentmodule:: cm.chef_rsa
+
+.. automodule:: cm.chef_rsa
+    :members:
+    :undoc-members:
diff --git a/docs/server/cm.mock.rst b/docs/server/cm.mock.rst
@@ -0,0 +1,14 @@
+:description: Python API Reference for the Deis cm.mock module
+:keywords: deis, cm.mock, python, celery, configuration management, mock, api
+
+=======
+cm.mock
+=======
+
+.. contents::
+    :local:
+.. currentmodule:: cm.mock
+
+.. automodule:: cm.mock
+    :members:
+    :undoc-members:
diff --git a/docs/server/index.rst b/docs/server/index.rst
@@ -19,18 +19,20 @@ Server Reference
     api.models
     api.routers
     api.serializers
+    api.ssh
+    api.tasks
     api.urls
     api.utils
     api.views
 
-    celerytasks.azuresms
-    celerytasks.chef
-    celerytasks.chef_mock
-    celerytasks.chef_rsa
-    celerytasks.controller
-    celerytasks.ec2
-    celerytasks.mock
-    celerytasks.util
+    cm.chef
+    cm.chef_api
+    cm.chef_rsa
+    cm.mock
+
+    provider.controller
+    provider.ec2
+    provider.mock
 
     web.urls
     web.views
diff --git a/docs/server/provider.controller.rst b/docs/server/provider.controller.rst
@@ -0,0 +1,19 @@
+:description: Python API Reference for the Deis provider.controller module
+:keywords: deis, provider.controller, python, celery, api
+
+===================
+provider.controller
+===================
+
+.. contents::
+    :local:
+.. currentmodule:: provider.controller
+
+.. automodule:: provider.controller
+    :members:
+    :undoc-members:
+
+    .. autofunction:: update_gitosis(databag_item_value)
+    .. autofunction:: update_formation(formation_id, databag_item_value)
+    .. autofunction:: update_application(app_id, databag_item_value)
+    .. autofunction:: destroy_formation(formation_id)
diff --git a/docs/server/provider.ec2.rst b/docs/server/provider.ec2.rst
@@ -0,0 +1,14 @@
+:description: Python API Reference for the Deis provider.ec2 module
+:keywords: deis, provider.ec2, python, celery, ec2, api
+
+============
+provider.ec2
+============
+
+.. contents::
+    :local:
+.. currentmodule:: provider.ec2
+
+.. automodule:: provider.ec2
+    :members:
+    :undoc-members:
diff --git a/docs/server/provider.mock.rst b/docs/server/provider.mock.rst
@@ -0,0 +1,14 @@
+:description: Python API Reference for the Deis provider.mock module
+:keywords: deis, provider.mock, python, celery, api
+
+=============
+provider.mock
+=============
+
+.. contents::
+    :local:
+.. currentmodule:: provider.mock
+
+.. automodule:: provider.mock
+    :members:
+    :undoc-members: