Extract configuration into dedicated doc page

docs/index.rst

@@ -9,6 +9,7 @@ Salt Extension for interacting with Apache Zookeeper
   :hidden:
 
   topics/installation
+  topics/configuration
 
 .. toctree::
   :maxdepth: 2

docs/topics/configuration.md

@@ -0,0 +1,54 @@
+(zookeeper-setup)=
+# Configuration
+This Salt extension requires configuration, either in the minion's config file or via the Pillar.
+
+## Basic
+```yaml
+zookeeper:
+  hosts: zoo1,zoo2,zoo3
+  default_acl:
+    - username: daniel
+      password: test
+      read: true
+      write: true
+      create: true
+      delete: true
+      admin: true
+  username: daniel
+  password: test
+```
+
+## Multiple environments
+If configuration for multiple zookeeper environments is required, they can
+be set up as different configuration profiles. For example:
+
+```yaml
+zookeeper:
+  prod:
+    hosts: zoo1,zoo2,zoo3
+    default_acl:
+      - username: daniel
+        password: test
+        read: true
+        write: true
+        create: true
+        delete: true
+        admin: true
+    username: daniel
+    password: test
+  dev:
+    hosts:
+      - dev1
+      - dev2
+      - dev3
+    default_acl:
+      - username: daniel
+        password: test
+        read: true
+        write: true
+        create: true
+        delete: true
+        admin: true
+    username: daniel
+    password: test
+```

src/saltext/zookeeper/modules/zookeeper.py

@@ -1,73 +1,12 @@
 """
-Zookeeper Module
-~~~~~~~~~~~~~~~~
-:maintainer:    SaltStack
-:maturity:      new
-:platform:      all
-:depends:       kazoo
-
-.. versionadded:: 2018.3.0
-
-Configuration
-=============
-
-:configuration: This module is not usable until the following are specified
-    either in a pillar or in the minion's config file:
-
-    .. code-block:: yaml
-
-        zookeeper:
-          hosts: zoo1,zoo2,zoo3
-          default_acl:
-            - username: daniel
-              password: test
-              read: true
-              write: true
-              create: true
-              delete: true
-              admin: true
-          username: daniel
-          password: test
-
-    If configuration for multiple zookeeper environments is required, they can
-    be set up as different configuration profiles. For example:
-
-    .. code-block:: yaml
-
-        zookeeper:
-          prod:
-            hosts: zoo1,zoo2,zoo3
-            default_acl:
-              - username: daniel
-                password: test
-                read: true
-                write: true
-                create: true
-                delete: true
-                admin: true
-            username: daniel
-            password: test
-          dev:
-            hosts:
-              - dev1
-              - dev2
-              - dev3
-            default_acl:
-              - username: daniel
-                password: test
-                read: true
-                write: true
-                create: true
-                delete: true
-                admin: true
-            username: daniel
-            password: test
+Interface with a Zookeeper service.
+
+.. important::
+    This module requires the general :ref:`Zookeeper setup <zookeeper-setup>`.
 """
 
-# Import Salt libraries
 import salt.utils.stringutils
 
-# Import python libraries
 try:
     import kazoo.client
     import kazoo.security

src/saltext/zookeeper/states/zookeeper.py

@@ -1,30 +1,42 @@
 """
-Zookeeper State
+Manage Zookeeper znodes and ACLs statefully.
 
-:depends:  kazoo
-:configuration: See :py:mod:`salt.modules.zookeeper` for setup instructions.
+.. important::
+    This module requires the general :ref:`Zookeeper setup <zookeeper-setup>`.
 
-ACLS
-~~~~
+ACLs
+----
 
-For more information about acls, please checkout the kazoo documentation.
+For more information about ACLs, please checkout the kazoo documentation.
 
-http://kazoo.readthedocs.io/en/latest/api/security.html#kazoo.security.make_digest_acl
+https://kazoo.readthedocs.io/en/latest/api/security.html#kazoo.security.make_digest_acl
 
+.. _acl-dicts:
+
+ACL dictionaries
+~~~~~~~~~~~~~~~~
 The following options can be included in the acl dictionary:
 
-    :param username: Username to use for the ACL.
-    :param password: A plain-text password to hash.
-    :param write: Write permission.
-    :type write: bool
-    :param create: Create permission.
-    :type create: bool
-    :param delete: Delete permission.
-    :type delete: bool
-    :param admin: Admin permission.
-    :type admin: bool
-    :param all: All permissions.
-    :type all: bool
+username
+    Username to use for the ACL.
+
+password
+    A plain-text password to hash.
+
+write [bool]
+    Write permission.
+
+create [bool]
+    Create permission.
+
+delete [bool]
+    Delete permission.
+
+admin [bool]
+    Admin permission.
+
+all [bool]
+    All permissions.
 """
 
 __virtualname__ = "zookeeper"
@@ -330,7 +342,7 @@ def acls(
         path to znode
 
     acls
-        list of acl dictionaries to set on znode
+        list of :ref:`acl dictionaries <acl-dicts>` to set on znode
 
     version
         Specify the version which should be deleted