Documentation updates

docs/source/index.rst

@@ -32,6 +32,8 @@ Turn that tedious task of provisioning the infrastructure of your website into a
 Documentation
 =============
 
+(:doc:`Looking for the API? Here's a shortcut! </api/modules>`)
+
 * :doc:`whats-provy`
 * :doc:`installing`
 * :doc:`getting-started`

provy/more/debian/networking/hosts.py

@@ -11,17 +11,15 @@
 class HostsRole(Hosts):
     '''
     This role provides hosts file management utilities for debian distributions.
-    <em>Sample usage</em>
-    <pre class="sh_python">
-    from provy.core import Role
-    from provy.more.debian import HostsRole
 
-    class MySampleRole(Role):
-        def provision(self):
-            with self.using(HostsRole) as role:
-                role.ensure_host('localhost', '127.0.0.1')
-    </pre>
-    '''
+    Example:
+    ::
+
+        from provy.core import Role
+        from provy.more.debian import HostsRole
 
-    def ensure_host(self, host_name, ip):
-        super(HostsRole, self).ensure_host(host_name, ip)
+        class MySampleRole(Role):
+            def provision(self):
+                with self.using(HostsRole) as role:
+                    role.ensure_host('localhost', '127.0.0.1')
+    '''

provy/more/linux/networking/hosts.py

@@ -11,17 +11,26 @@
 class HostsRole(Role):
     '''
     This role provides hosts file management utilities.
-    <em>Sample usage</em>
-    <pre class="sh_python">
-    from provy.core import Role
-    from provy.more.linux import HostsRole
-
-    class MySampleRole(Role):
-        def provision(self):
-            with self.using(HostsRole) as role:
-                role.ensure_host('localhost', '127.0.0.1')
-    </pre>
+
+    Example:
+    ::
+
+        from provy.core import Role
+        from provy.more.linux import HostsRole
+
+        class MySampleRole(Role):
+            def provision(self):
+                with self.using(HostsRole) as role:
+                    role.ensure_host('localhost', '127.0.0.1')
     '''
 
     def ensure_host(self, host_name, ip):
+        '''
+        Makes sure that a certain host is configured in the hosts file.
+
+        :param host_name: The hostname.
+        :type host_name: :class:`str`
+        :param ip: The IP to which the :data:`host_name` will point to.
+        :type ip: :class:`str`
+        '''
         self.ensure_line('%s        %s' % (ip, host_name), '/etc/hosts', sudo=True)