This commit adds support for pybind11 docstrings. It also contains se…

…veral updates

explained below.

* Add a tutorial to explain how to get started using the package.
* Support PEP-484 annotations.
* Allow type information to be passed to the parser.
* Issue warnings for args that have no documentation.
* Add several configurable options to the parser.
* Fix extraction of multi-line function signatures
* Fix over-loaded functions.

README.md

@@ -1,123 +1,24 @@
 # MyDocstring
-[MyDocstring](README.md) is a small Python package that allows you to extract docstrings display them as either plain-text, [Markdown](http://commonmark.org/), or [JSON](https://www.json.org/) data.
+[MyDocstring](README.md) is a small Python package that allows you to extract and parse docstrings. It suited for building your own documentation system. Docstrings can be displayed as either plain-text, [Markdown](http://commonmark.org/), or [JSON](https://www.json.org/) data.
 
-* Support for Python-code  (support for C-code is planned).
-* Support for [Google-style docstrings](http://google.github.io/styleguide/pyguide.html)
+* Supports [Python PEP484 type hints](https://www.python.org/dev/peps/pep-0484/).
+* Supports [pybind11](https://github.com/pybind/pybind11) docstrings.
+* Supports [Google-style docstrings](http://google.github.io/styleguide/pyguide.html).
 * Produces [JSON](https://www.json.org/), plain-text, and [Markdown](http://commonmark.org/) output for modules, classes, functions, and
   methods.
 
 ## Getting Started
-You can begin extracting and converting docstrings using the command line tool
-`mydocstring` that comes with package. Simply type `mydocstring --help` to see how to use it. 
+If you are interested in building a documentation solution for your own
+project, a good place to
+start is this [tutorial](tutorials/begin.ipynb). This tutorial will teach you
+how to extract and parse docstrings. 
 
-Let's extract the docstring from the following example code and convert it to
-Markdown:
-```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:
-
-        `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
-```
-This example code can be found here: [examples/example.py](examples/example.py).
-
-To convert to Markdown, we simply use
-```
-$ docstring examples/example.py example_function --markdown > examples/example_py.md
-```
-The following rendered Markdown is produced: 
-
----
-# 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
-
-```
-
----
-The output above can also be found here: [examples/example_py.md](examples/example_py.md).
-
-If you are not satisfied with the resulting Markdown, you can provide your own
-[mako](http://makotemplates.org) template
-
-```
-$ docstring examples/example.py example_function --markdown --template customization.md
-```
-Go to [mydocstring/templates/](mydocstring/templates/) to see how to make your own
-template. 
-
-It is also possible to output plain-text, or JSON-data using the flags args
-`--text` and `--json`. Example output can be found here: [examples/](examples/).
+If you are after a complete documentation solution, then see the
+[showcase](#showcase) section that features solutions built on *MyDocstring*.
 
+The project also comes with a command line tool that serves as an example of
+what you can build with the package. See [here](examples/README.md) for learning
+how to use the command line tool and to see some example output.
 
 ## Installation
 The package is available on the Python packaging index [PyPi](https://pypi.python.org/pypi) and can be installed via pip as follows.
@@ -127,7 +28,7 @@ $ pip install mydocstring
 
 ## Dependencies
 This project uses:
-* [docopt](http://docopt.org/) for the command-line interface application. 
+* [docopt](http://docopt.org/) for the command line interface application. 
 * [mako](http://www.makotemplates.org/) for producing markdown templates.
 * [pytest](https://docs.pytest.org/en/latest/) for testing.
 
@@ -143,28 +44,19 @@ Otherwise, please submit a new issue using the [issue tracker](https://github.co
 
 ## Contributing
 Contributions are more than welcome. Please reach out via the issue tracker to
-discuss and also see [here](contributing.md) for
+discuss and also see [here](CONTRIBUTING.md) for
 some guidelines.
 
 ##  Showcase 
 If you end up using this tool in your project in one way or another. I would
 love to hear about it and showcase it here. Please go ahead and make a pull
 request. 
 
-## Acknowledgments
-These are some projects that inspired me to develop this tool. 
-* [pdoc](https://github.com/BurntSushi/pdoc/) A tool for auto-generating API
-  documentation for Python libraries.
-* [mkdocs](http://www.mkdocs.org/) Static site generator for building
-  documentation using markdown. 
-* [moxygen](https://github.com/sourcey/moxygen) Doxygen XML to Markdown
-  converter.
-* [napoleon](https://pypi.python.org/pypi/sphinxcontrib-napoleon) Sphinx
-  extension that can parse numpy and Google-style docstrings.
-* [pypydoxify](https://pypi.python.org/pypi/doxypypy/0.8.8.6) Converts Python
-  comments into Doxygen's syntax.
-* [docsify](https://github.com/QingWei-Li/docsify/) Markdown-based documentation
-  site generator.
+* [NetKet](https://www.netket.org) is a open-source project for machine learning and
+  many-body quantum systems. It uses *mydocstring* for generating reference
+  documentation from [pybind11](https://github.com/pybind/pybind11) docstrings.
+  See
+  [here](https://github.com/netket/netket/tree/v2.0/Docs) for the source. 
 
 ## License
 

examples.sh

@@ -0,0 +1,2 @@
+mydocstring examples/example.py example_function --json >> examples/example.json
+mydocstring examples/example.py example_function --markdown >> examples/example.md

examples/README.md

@@ -0,0 +1,112 @@
+# Command line tool
+To learn how to use the command line tool, simply type `mydocstring --help`.
+
+Let's extract the docstring from the following example code and convert it to
+Markdown:
+```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:
+
+        `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
+```
+This example code can be found here: [example.py](example.py).
+
+To convert to Markdown, we simply use
+```
+$ docstring examples/example.py example_function --markdown > examples/example_py.md
+```
+The following rendered Markdown is produced: 
+
+---
+# 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
+
+```
+
+---
+The output above can also be found here: [example_py.md](example_py.md).
+
+If you are not satisfied with the resulting Markdown, you can provide your own
+[mako](http://makotemplates.org) template
+
+```
+$ docstring examples/example.py example_function --markdown --template customization.md
+```
+Go to [mydocstring/templates/](../mydocstring/templates/) to see how to make your own
+template. 
+
+It is also possible to output plain-text, or JSON-data using the flags args
+`--text` and `--json`. 
+
+

examples/example_py.json → examples/example.json

@@ -18,7 +18,7 @@
             }
         ],
         "header": "Arguments",
-        "text": "\n"
+        "text": ""
     },
     {
         "args": [
@@ -29,7 +29,7 @@
             }
         ],
         "header": "Returns",
-        "text": "\n\nWe can continue putting explanations in this section as long as the text\nis indented.\n"
+        "text": "\nWe can continue putting explanations in this section as long as the text\nis indented.\n"
     },
     {
         "args": [],
@@ -39,13 +39,18 @@
     {
         "args": [
             {
-                "description": "This is exception is raised when arg1 and arg2 are the same.",
+                "description": "This is exception is raised when arg1 and arg2 are equal.",
                 "field": "ValueError",
                 "signature": ""
             }
         ],
         "header": "Raises",
-        "text": "\n\n"
+        "text": ""
+    },
+    {
+        "args": [],
+        "header": "Examples",
+        "text": "\nCode block 1.\n>>> a = 0\n>>> a\n0\n\nCode block 2.\n>>> b = 1\n>>> b\n1\n\n"
     },
     {}
 ]

examples/example_py.md → examples/example.md

@@ -16,11 +16,9 @@ with a header such as `Arguments` or `Returns` and its contents is indented.
 * **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.
 
@@ -31,14 +29,31 @@ section.
 ## Raises
 * **ValueError**  : This is exception is raised when arg1 and arg2 are equal.
 
+## Examples
+
+Code block 1.
+
+```python
+
+>>> a
+0
 
+```
+Code block 2.
+
+```python
+
+>>> b
+1
+
+```
 
 
 ## Source
 ```python
 def example_function(arg1, arg2=1):
     if arg1 == arg2:
-        raise ValueError("`arg1` and `arg2` cannot be equal")
+        raise ValueError("`arg1` and `arg2` cannot be equal.")
     if arg1 > arg2:
         return True
     else: