From fe2bc8989bb89ef48c75cf206322798fa50341f3 Mon Sep 17 00:00:00 2001
From: Ossian O'Reilly <ooreilly@stanford.edu>
Date: Wed, 3 Jan 2018 01:23:32 -0800
Subject: [PATCH] Add examples.

---
 examples/example.py      | 33 ++++++++++++++++++++++++++
 examples/example.sh      |  3 +++
 examples/example_py.json | 51 ++++++++++++++++++++++++++++++++++++++++
 examples/example_py.md   | 48 +++++++++++++++++++++++++++++++++++++
 examples/example_py.txt  | 27 +++++++++++++++++++++
 setup.py                 |  2 +-
 6 files changed, 163 insertions(+), 1 deletion(-)
 create mode 100644 examples/example.py
 create mode 100644 examples/example.sh
 create mode 100644 examples/example_py.json
 create mode 100644 examples/example_py.md
 create mode 100644 examples/example_py.txt

diff --git a/examples/example.py b/examples/example.py
new file mode 100644
index 0000000..33aadd2
--- /dev/null
+++ b/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
diff --git a/examples/example.sh b/examples/example.sh
new file mode 100644
index 0000000..8d2b2a4
--- /dev/null
+++ b/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
diff --git a/examples/example_py.json b/examples/example_py.json
new file mode 100644
index 0000000..41b1b7b
--- /dev/null
+++ b/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"
+    },
+    {}
+]
diff --git a/examples/example_py.md b/examples/example_py.md
new file mode 100644
index 0000000..eab74bb
--- /dev/null
+++ b/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
+
+```
+
diff --git a/examples/example_py.txt b/examples/example_py.txt
new file mode 100644
index 0000000..038df8e
--- /dev/null
+++ b/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.
+
+
diff --git a/setup.py b/setup.py
index cab44fe..0dd8bd9 100644
--- a/setup.py
+++ b/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',