Add examples.

Author: Ossian O'Reilly

examples/example.py

@@ -0,0 +1,33 @@
+def example_function(arg1, arg2=1):
+    """
+    This is an example of a docstring that conforms to the Google style guide. 
+    The indentation uses four spaces (no tabs). Note that each section starts
+    with a header such as `Arguments` or `Returns` and its contents is indented.
+
+    Arguments:
+
+        arg1 (`int`): This description for this argument fits on one line.
+        arg2 (`int`, optional): This description is too long to fit on a
+            single line. Note that it is continued by being indented. 
+
+    Returns:
+
+        `bool` :  Stating the return type here is optional.
+
+        We can continue putting explanations in this section as long as the text
+        is indented.
+
+    This text is no longer indented and therefore not part of the `Returns`
+    section.
+
+    Raises:
+
+        ValueError: This is exception is raised when arg1 and arg2 are equal.
+
+    """
+    if arg1 == arg2:
+        raise ValueError("`arg1` and `arg2` cannot be equal.")
+    if arg1 > arg2:
+        return True
+    else: 
+        return False

examples/example.sh

@@ -0,0 +1,3 @@
+docstring examples/example.py example_function --text > examples/example_py.txt
+docstring examples/example.py example_function --markdown > examples/example_py.md
+docstring examples/example.py example_function --json > examples/example_py.json

examples/example_py.json

@@ -0,0 +1,51 @@
+[
+    {
+        "args": [],
+        "header": "",
+        "text": "\n\nThis is an example of a docstring that conforms to the Google style guide. \nThe indentation uses four spaces (no tabs). Note that each section starts\nwith a header such as `Arguments` or `Returns` and its contents is indented.\n"
+    },
+    {
+        "args": [
+            {
+                "description": "This description for this argument fits on one line.",
+                "field": "arg1",
+                "signature": "(`int`)"
+            },
+            {
+                "description": "This description is too long to fit on a\n    single line. Note that it is continued by being indented. ",
+                "field": "arg2",
+                "signature": "(`int`, optional)"
+            }
+        ],
+        "header": "Arguments",
+        "text": "\n"
+    },
+    {
+        "args": [
+            {
+                "description": " Stating the return type here is optional.",
+                "field": "",
+                "signature": ""
+            }
+        ],
+        "header": "Returns",
+        "text": "\n\nWe can continue putting explanations in this section as long as the text\nis indented.\n"
+    },
+    {
+        "args": [],
+        "header": "",
+        "text": "This text is no longer indented and therefore not part of the `Returns`\nsection.\n"
+    },
+    {
+        "args": [
+            {
+                "description": "This is exception is raised when arg1 and arg2 are the same.",
+                "field": "ValueError",
+                "signature": ""
+            }
+        ],
+        "header": "Raises",
+        "text": "\n\n"
+    },
+    {}
+]

examples/example_py.md

@@ -0,0 +1,48 @@
+
+# example_function
+```python
+def example_function(arg1, arg2=1):
+```
+
+---
+
+
+This is an example of a docstring that conforms to the Google style guide. 
+The indentation uses four spaces (no tabs). Note that each section starts
+with a header such as `Arguments` or `Returns` and its contents is indented.
+
+## Arguments
+* **arg1** (`int`) : This description for this argument fits on one line.
+* **arg2** (`int`, optional) : This description is too long to fit on a
+    single line. Note that it is continued by being indented. 
+
+
+## Returns
+*  Stating the return type here is optional.
+
+
+We can continue putting explanations in this section as long as the text
+is indented.
+
+---
+This text is no longer indented and therefore not part of the `Returns`
+section.
+
+## Raises
+* **ValueError**  : This is exception is raised when arg1 and arg2 are equal.
+
+
+
+
+## Source
+```python
+def example_function(arg1, arg2=1):
+    if arg1 == arg2:
+        raise ValueError("`arg1` and `arg2` cannot be equal")
+    if arg1 > arg2:
+        return True
+    else: 
+        return False
+
+```
+

examples/example_py.txt

@@ -0,0 +1,27 @@
+example_function(arg1, arg2=1)
+
+This is an example of a docstring that conforms to the Google style guide. 
+The indentation uses four spaces (no tabs). Note that each section starts
+with a header such as `Arguments` or `Returns` and its contents is indented.
+
+Arguments:
+
+    arg1 (`int`): This description for this argument fits on one line.
+    arg2 (`int`, optional): This description is too long to fit on a
+        single line. Note that it is continued by being indented. 
+
+Returns:
+
+    `bool` :  Stating the return type here is optional.
+
+    We can continue putting explanations in this section as long as the text
+    is indented.
+
+This text is no longer indented and therefore not part of the `Returns`
+section.
+
+Raises:
+
+    ValueError: This is exception is raised when arg1 and arg2 are the same.
+
+

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup
 
 setup(name='mydocstring',
-      version='0.1.0',
+      version='0.1.1',
       description="""A tool for extracting and converting Google-style docstrings to
       plain-text, markdown, and JSON.""",
       url='http://github.com/ooreilly/mydocstring',