DOC: cleanup docstring for read_json and fix error in contribution guide

doc/source/development/contributing.rst

@@ -288,7 +288,7 @@ complex changes to the documentation as well.
 Some other important things to know about the docs:
 
 * The *pandas* documentation consists of two parts: the docstrings in the code
-  itself and the docs in this folder ``pandas/doc/``.
+  itself and the docs in this folder ``doc/``.
 
   The docstrings provide a clear explanation of the usage of the individual
   functions, while the documentation in this folder consists of tutorial-like
@@ -404,11 +404,11 @@ Building the documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 So how do you build the docs? Navigate to your local
-``pandas/doc/`` directory in the console and run::
+``doc/`` directory in the console and run::
 
     python make.py html
 
-Then you can find the HTML output in the folder ``pandas/doc/build/html/``.
+Then you can find the HTML output in the folder ``doc/build/html/``.
 
 The first time you build the docs, it will take quite a while because it has to run
 all the code examples and build all the generated docstring pages. In subsequent
@@ -448,7 +448,7 @@ You can also specify to use multiple cores to speed up the documentation build::
 Open the following file in a web browser to see the full documentation you
 just built::
 
-    pandas/docs/build/html/index.html
+    doc/build/html/index.html
 
 And you'll have the satisfaction of seeing your new and improved documentation!
 

pandas/io/json/_json.py

@@ -352,12 +352,12 @@ def read_json(
 
     Parameters
     ----------
-    path_or_buf : a valid JSON string or file-like, default: None
+    path_or_buf : a valid JSON string or file-like, default None
         The string could be a URL. Valid URL schemes include http, ftp, s3,
         gcs, and file. For file URLs, a host is expected. For instance, a local
-        file could be ``file://localhost/path/to/table.json``
+        file could be ``file://localhost/path/to/table.json``.
 
-    orient : string,
+    orient : str, default None
         Indication of expected JSON string format.
         Compatible JSON strings can be produced by ``to_json()`` with a
         corresponding orient value.
@@ -393,8 +393,10 @@ def read_json(
         .. versionadded:: 0.23.0
            'table' as an allowed value for the ``orient`` argument
 
-    typ : type of object to recover (series or frame), default 'frame'
-    dtype : boolean or dict, default None
+    typ : {'frame', 'series'}, default 'frame'
+        The type of object to recover.
+
+    dtype : bool or dict, default None
         If True, infer dtypes; if a dict of column to dtype, then use those;
         if False, then don't infer dtypes at all, applies only to the data.
 
@@ -404,7 +406,7 @@ def read_json(
 
            Not applicable for ``orient='table'``.
 
-    convert_axes : boolean, default None
+    convert_axes : bool, default None
         Try to convert the axes to the proper dtypes.
 
         For all ``orient`` values except ``'table'``, default is True.
@@ -413,9 +415,9 @@ def read_json(
 
            Not applicable for ``orient='table'``.
 
-    convert_dates : boolean, default True
-        List of columns to parse for dates; If True, then try to parse
-        datelike columns default is True; a column label is datelike if
+    convert_dates : bool or list of str, default True
+        List of columns to parse for dates. If True, then try to parse
+        datelike columns. A column label is datelike if
 
         * it ends with ``'_at'``,
 
@@ -425,34 +427,38 @@ def read_json(
 
         * it is ``'modified'``, or
 
-        * it is ``'date'``
+        * it is ``'date'``.
+
+    keep_default_dates : bool, default True
+        If parsing dates, then parse the default datelike columns.
 
-    keep_default_dates : boolean, default True
-        If parsing dates, then parse the default datelike columns
-    numpy : boolean, default False
+    numpy : bool, default False
         Direct decoding to numpy arrays. Supports numeric data only, but
         non-numeric column and index labels are supported. Note also that the
         JSON ordering MUST be the same for each term if numpy=True.
-    precise_float : boolean, default False
+
+    precise_float : bool, default False
         Set to enable usage of higher precision (strtod) function when
         decoding string to double values. Default (False) is to use fast but
-        less precise builtin functionality
-    date_unit : string, default None
+        less precise builtin functionality.
+
+    date_unit : str, default None
         The timestamp unit to detect if converting dates. The default behaviour
         is to try and detect the correct precision, but if this is not desired
         then pass one of 's', 'ms', 'us' or 'ns' to force parsing only seconds,
         milliseconds, microseconds or nanoseconds respectively.
+
     encoding : str, default is 'utf-8'
         The encoding to use to decode py3 bytes.
 
         .. versionadded:: 0.19.0
 
-    lines : boolean, default False
+    lines : bool, default False
         Read the file as a json object per line.
 
         .. versionadded:: 0.19.0
 
-    chunksize : integer, default None
+    chunksize : int, optional
         Return JsonReader object for iteration.
         See the `line-delimited json docs
         <http://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#line-delimited-json>`_
@@ -473,11 +479,13 @@ def read_json(
 
     Returns
     -------
-    result : Series or DataFrame, depending on the value of `typ`.
+    Series or DataFrame
+        The type returned depends on the value of `typ`.
 
     See Also
     --------
-    DataFrame.to_json
+    DataFrame.to_json : Convert a DataFrame to a JSON string.
+    Series.to_json : Convert a Series to a JSON string.
 
     Notes
     -----