Merge pull request splunk#245 from lowell80/fix-the-docs

shakeelmohamed · web-flow · commit e30936a9d6d7 · 2019-02-22T17:12:37.000-08:00
Fix the docs
diff --git a/README.md b/README.md
@@ -1,4 +1,6 @@
 [![Build Status](https://travis-ci.org/splunk/splunk-sdk-python.svg?branch=master)](https://travis-ci.org/splunk/splunk-sdk-python)
+[![Documentation Status](https://readthedocs.org/projects/splunk-python-sdk/badge/?version=latest)](https://splunk-python-sdk.readthedocs.io/en/latest/?badge=latest)
+
 # The Splunk Software Development Kit for Python
 
 #### Version 1.6.6
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,6 +3,16 @@ For more information, see the `Splunk Developer Portal <http://dev.splunk.com/vi
 
 .. toctree::
    :maxdepth: 2
+   :name: SDK for Python API Reference
+
+   binding
+   client
+   data
+   results
+   modularinput
+   searchcommands
+   searchcommandsvalidators
+
 
 :doc:`binding`
 --------------
diff --git a/docs/searchcommands.rst b/docs/searchcommands.rst
@@ -80,10 +80,6 @@ splunklib.searchcommands
     :members:
     :inherited-members:
 
-.. autoclass:: Fieldname
-    :members:
-    :inherited-members:
-
 .. autoclass:: File
     :members:
     :inherited-members:
@@ -100,6 +96,3 @@ splunklib.searchcommands
     :members:
     :inherited-members:
 
-.. autoclass:: Validator
-    :members:
-    :inherited-members:
diff --git a/docs/searchcommandsvalidators.rst b/docs/searchcommandsvalidators.rst
@@ -0,0 +1,12 @@
+splunklib.searchcommands.validators
+-----------------------------------
+
+.. automodule:: splunklib.searchcommands.validators
+
+.. autoclass:: Fieldname
+    :members:
+    :inherited-members:
+
+.. autoclass:: Validator
+    :members:
+    :inherited-members:
diff --git a/splunklib/binding.py b/splunklib/binding.py
@@ -80,6 +80,7 @@ def _parse_cookies(cookie_str, dictionary):
     then updates the the dictionary with any key-value pairs found.
 
     **Example**::
+
         dictionary = {}
         _parse_cookies('my=value', dictionary)
         # Now the following is True
diff --git a/splunklib/client.py b/splunklib/client.py
@@ -1200,7 +1200,7 @@ def __getitem__(self, key):
         :raises ValueError: Raised if no namespace is specified and *key*
                             does not refer to a unique name.
 
-        *Example*::
+        **Example**::
 
             s = client.connect(...)
             saved_searches = s.saved_searches
@@ -1636,9 +1636,9 @@ def get(self, name="", owner=None, app=None, sharing=None, **query):
         :rtype: ``dict`` with keys ``body``, ``headers``, ``reason``,
                 and ``status``
 
-        Example:
+        **Example**::
 
-        import splunklib.client
+            import splunklib.client
             s = client.service(...)
             saved_searches = s.saved_searches
             saved_searches.get("my/saved/search") == \\
diff --git a/splunklib/modularinput/argument.py b/splunklib/modularinput/argument.py
@@ -54,9 +54,9 @@ def __init__(self, name, description=None, validation=None,
         :param name: ``string``, identifier for this argument in Splunk.
         :param description: ``string``, human-readable description of the argument.
         :param validation: ``string`` specifying how the argument should be validated, if using internal validation.
-        If using external validation, this will be ignored.
+               If using external validation, this will be ignored.
         :param data_type: ``string``, data type of this field; use the class constants.
-        "data_type_boolean", "data_type_number", or "data_type_string".
+               "data_type_boolean", "data_type_number", or "data_type_string".
         :param required_on_edit: ``Boolean``, whether this arg is required when editing an existing modular input of this kind.
         :param required_on_create: ``Boolean``, whether this arg is required when creating a modular input of this kind.
         :param title: ``String``, a human-readable title for the argument.
diff --git a/splunklib/modularinput/scheme.py b/splunklib/modularinput/scheme.py
@@ -55,7 +55,7 @@ def add_argument(self, arg):
     def to_xml(self):
         """Creates an ``ET.Element`` representing self, then returns it.
 
-        :returns root, an ``ET.Element`` representing this scheme.
+        :returns: an ``ET.Element`` representing this scheme.
         """
         root = ET.Element("scheme")
 
diff --git a/splunklib/modularinput/script.py b/splunklib/modularinput/script.py
@@ -118,9 +118,9 @@ def service(self):
         available as soon as the :code:`Script.stream_events` method is
         called.
 
-        :return: :class:splunklib.client.Service. A value of None is returned,
-        if you call this method before the :code:`Script.stream_events` method
-        is called.
+        :return: :class:`splunklib.client.Service`. A value of None is returned,
+            if you call this method before the :code:`Script.stream_events` method
+            is called.
 
         """
         if self._service is not None:
diff --git a/splunklib/modularinput/validation_definition.py b/splunklib/modularinput/validation_definition.py
@@ -28,7 +28,7 @@ class ValidationDefinition(object):
 
     **Example**::
 
-    ``v = ValidationDefinition()``
+        v = ValidationDefinition()
 
     """
     def __init__(self):
@@ -46,23 +46,25 @@ def parse(stream):
 
         The XML typically will look like this:
 
-        ``<items>``
-        ``   <server_host>myHost</server_host>``
-        ``     <server_uri>https://127.0.0.1:8089</server_uri>``
-        ``     <session_key>123102983109283019283</session_key>``
-        ``     <checkpoint_dir>/opt/splunk/var/lib/splunk/modinputs</checkpoint_dir>``
-        ``     <item name="myScheme">``
-        ``       <param name="param1">value1</param>``
-        ``       <param_list name="param2">``
-        ``         <value>value2</value>``
-        ``         <value>value3</value>``
-        ``         <value>value4</value>``
-        ``       </param_list>``
-        ``     </item>``
-        ``</items>``
+        ..  code-block:: xml
+
+            <items>
+               <server_host>myHost</server_host>
+                 <server_uri>https://127.0.0.1:8089</server_uri>
+                 <session_key>123102983109283019283</session_key>
+                 <checkpoint_dir>/opt/splunk/var/lib/splunk/modinputs</checkpoint_dir>
+                 <item name="myScheme">
+                   <param name="param1">value1</param>
+                   <param_list name="param2">
+                     <value>value2</value>
+                     <value>value3</value>
+                     <value>value4</value>
+                   </param_list>
+                 </item>
+            </items>
 
         :param stream: ``Stream`` containing XML to parse.
-        :return definition: A ``ValidationDefinition`` object.
+        :return: A ``ValidationDefinition`` object.
 
         """
 
diff --git a/splunklib/searchcommands/__init__.py b/splunklib/searchcommands/__init__.py
@@ -30,7 +30,7 @@
         field-name    = ( "_" / alpha ) *( alpha / digit / "_" / "." / "-" )
 
      It does not show that :code:`field-name` values may be comma-separated. This is because Splunk strips commas from
-    the command line. A search command will never see them.
+     the command line. A search command will never see them.
 
   2. Search commands targeting versions of Splunk prior to 6.3 must be statically configured as follows:
 
@@ -134,7 +134,7 @@
 
 .. topic:: References
 
-  1. `Search command style guide <http://docs.splunk.com/Documentation/Splunk/6.0/Search/Searchcommandstyleguide>`_
+  1. `Search command style guide <http://docs.splunk.com/Documentation/Splunk/6.0/Search/Searchcommandstyleguide>`__
 
   2. `Commands.conf.spec <http://docs.splunk.com/Documentation/Splunk/5.0.5/Admin/Commandsconf>`_
 
diff --git a/splunklib/searchcommands/decorators.py b/splunklib/searchcommands/decorators.py
@@ -36,7 +36,7 @@ class Configuration(object):
     variable to search command classes that don't have one. The :code:`name` is derived from the name of the class.
     By convention command class names end with the word "Command". To derive :code:`name` the word "Command" is removed
     from the end of the class name and then converted to lower case for conformance with the `Search command style guide
-    <http://docs.splunk.com/Documentation/Splunk/latest/Search/Searchcommandstyleguide>`_
+    <http://docs.splunk.com/Documentation/Splunk/latest/Search/Searchcommandstyleguide>`__
 
     """
     def __init__(self, o=None, **kwargs):
@@ -229,8 +229,9 @@ class Option(property):
 
     Short form (recommended). When you are satisfied with built-in or custom validation behaviors.
 
-    .. code-block:: python
+    ..  code-block:: python
         :linenos:
+
         from splunklib.searchcommands.decorators import Option
         from splunklib.searchcommands.validators import Fieldname
 
@@ -247,8 +248,9 @@ class Option(property):
     also provide a deleter. You must be prepared to accept a value of :const:`None` which indicates that your
     :code:`Option` is unset.
 
-    .. code-block:: python
+    ..  code-block:: python
         :linenos:
+
         from splunklib.searchcommands import Option
 
         @Option()
diff --git a/splunklib/searchcommands/external_search_command.py b/splunklib/searchcommands/external_search_command.py
@@ -105,13 +105,13 @@ def _execute(path, argv=None, environ=None):
 
             :param argv: Argument list.
             :type argv: list or tuple
-            The arguments to the child process should start with the name of the command being run, but this is not
-            enforced. A value of :const:`None` specifies that the base name of path name :param:`path` should be used.
+                The arguments to the child process should start with the name of the command being run, but this is not
+                enforced. A value of :const:`None` specifies that the base name of path name :param:`path` should be used.
 
             :param environ: A mapping which is used to define the environment variables for the new process.
             :type environ: dict or None.
-            This mapping is used instead of the current process’s environment. A value of :const:`None` specifies that
-            the :data:`os.environ` mapping should be used.
+                This mapping is used instead of the current process’s environment. A value of :const:`None` specifies that
+                the :data:`os.environ` mapping should be used.
 
             :return: None
 
diff --git a/splunklib/searchcommands/generating_command.py b/splunklib/searchcommands/generating_command.py
@@ -92,9 +92,10 @@ class StreamingGeneratingCommand(GeneratingCommand)
     +==========+===================================================+===================================================+
     | streams  | 1. Add this line to your command's stanza in      | 1. Add this configuration setting to your code:   |
     |          |                                                   |                                                   |
-    |          |    default/commands.conf.                         |    .. code-block:: python                         |
-    |          |    .. code-block:: python                         |        @Configuration(distributed=True)           |
-    |          |        local = false                              |        class SomeCommand(GeneratingCommand)       |
+    |          |    default/commands.conf::                        |    ..  code-block:: python                        |
+    |          |                                                   |                                                   |
+    |          |        local = false                              |        @Configuration(distributed=True)           |
+    |          |                                                   |        class SomeCommand(GeneratingCommand)       |
     |          |                                                   |            ...                                    |
     |          | 2. Restart splunk                                 |                                                   |
     |          |                                                   | 2. You are good to go; no need to restart Splunk  |
@@ -112,29 +113,33 @@ class StreamingGeneratingCommand(GeneratingCommand)
     |          | settings to your command class:                   | setting to your command class:                    |
     |          |                                                   |                                                   |
     |          | .. code-block:: python                            | .. code-block:: python                            |
+    |          |                                                   |                                                   |
     |          |     @Configuration(                               |     @Configuration(type='events')                 |
     |          |         retainsevents=True, streaming=False)      |     class SomeCommand(GeneratingCommand)          |
     |          |     class SomeCommand(GeneratingCommand)          |         ...                                       |
     |          |         ...                                       |                                                   |
     |          |                                                   |                                                   |
     |          | Or add these lines to default/commands.conf:      |                                                   |
     |          |                                                   |                                                   |
-    |          | .. code-block::                                   |                                                   |
-    |          |     retains events = true                         |                                                   |
+    |          | ..  code-block:: text                             |                                                   |
+    |          |                                                   |                                                   |
+    |          |     retainsevents = true                          |                                                   |
     |          |     streaming = false                             |                                                   |
     +----------+---------------------------------------------------+---------------------------------------------------+
 
     Configure your command class like this, if you wish to support both protocols:
 
-    .. code-block:: python
+    ..  code-block:: python
+
         @Configuration(type='events', retainsevents=True, streaming=False)
         class SomeCommand(GeneratingCommand)
             ...
 
     You might also consider adding these lines to commands.conf instead of adding them to your command class:
 
-    .. code-block:: python
-        retains events = false
+    ..  code-block:: python
+
+        retainsevents = false
         streaming = false
 
     Reporting Generating command
@@ -149,28 +154,32 @@ class SomeCommand(GeneratingCommand)
     |          | settings to your command class:                   | setting to your command class:                    |
     |          |                                                   |                                                   |
     |          | .. code-block:: python                            | .. code-block:: python                            |
+    |          |                                                   |                                                   |
     |          |     @Configuration(retainsevents=False)           |     @Configuration(type='reporting')              |
     |          |     class SomeCommand(GeneratingCommand)          |     class SomeCommand(GeneratingCommand)          |
     |          |         ...                                       |         ...                                       |
     |          |                                                   |                                                   |
     |          | Or add this lines to default/commands.conf:       |                                                   |
     |          |                                                   |                                                   |
-    |          | .. code-block::                                   |                                                   |
-    |          |     retains events = false                        |                                                   |
+    |          | .. code-block:: text                              |                                                   |
+    |          |                                                   |                                                   |
+    |          |     retainsevents = false                         |                                                   |
     |          |     streaming = false                             |                                                   |
     +----------+---------------------------------------------------+---------------------------------------------------+
 
     Configure your command class like this, if you wish to support both protocols:
 
-    .. code-block:: python
+    ..  code-block:: python
+
         @Configuration(type='reporting', streaming=False)
         class SomeCommand(GeneratingCommand)
             ...
 
     You might also consider adding these lines to commands.conf instead of adding them to your command class:
 
-    .. code-block:: python
-        retains events = false
+    ..  code-block:: text
+
+        retainsevents = false
         streaming = false
 
     """
diff --git a/splunklib/searchcommands/search_command.py b/splunklib/searchcommands/search_command.py
@@ -256,7 +256,7 @@ def search_results_info(self):
         invocation.
 
         :return: Search results info:const:`None`, if the search results info file associated with the command
-        invocation is inaccessible.
+                 invocation is inaccessible.
         :rtype: SearchResultsInfo or NoneType
 
         """
@@ -338,15 +338,16 @@ def service(self):
         specifying this pair of configuration settings in commands.conf:
 
            .. code-block:: python
+
                enableheader = true
                requires_srinfo = true
 
         The :code:`enableheader` setting is :code:`true` by default. Hence, you need not set it. The
         :code:`requires_srinfo` setting is false by default. Hence, you must set it.
 
         :return: :class:`splunklib.client.Service`, if :code:`enableheader` and :code:`requires_srinfo` are both
-        :code:`true`. Otherwise, if either :code:`enableheader` or :code:`requires_srinfo` are :code:`false`, a value
-        of :code:`None` is returned.
+            :code:`true`. Otherwise, if either :code:`enableheader` or :code:`requires_srinfo` are :code:`false`, a value
+            of :code:`None` is returned.
 
         """
         if self._service is not None:
@@ -809,15 +810,15 @@ def write_metric(self, name, value):
         :param name: Name of the metric.
         :type name: basestring
 
-        :param value: A 4-tuple containing the value of metric :param:`name` where
+        :param value: A 4-tuple containing the value of metric ``name`` where
 
             value[0] = Elapsed seconds or :const:`None`.
             value[1] = Number of invocations or :const:`None`.
             value[2] = Input count or :const:`None`.
             value[3] = Output count or :const:`None`.
 
-        The :data:`SearchMetric` type provides a convenient encapsulation of :param:`value`.
-        The :data:`SearchMetric` type provides a convenient encapsulation of :param:`value`.
+        The :data:`SearchMetric` type provides a convenient encapsulation of ``value``.
+        The :data:`SearchMetric` type provides a convenient encapsulation of ``value``.
 
         :return: :const:`None`.
 
@@ -1080,7 +1081,7 @@ def dispatch(command_class, argv=sys.argv, input_file=sys.stdin, output_file=sys
 
     **Example**
 
-    .. code-block:: python
+    ..  code-block:: python
         :linenos:
 
         #!/usr/bin/env python
@@ -1096,7 +1097,7 @@ def stream(records):
 
     **Example**
 
-    .. code-block:: python
+    ..  code-block:: python
         :linenos:
 
         from splunklib.searchcommands import dispatch, StreamingCommand, Configuration, Option, validators
diff --git a/splunklib/searchcommands/validators.py b/splunklib/searchcommands/validators.py
