Repository: creisle/markdown_refdocs

Issue:
add admonitions for `Todo`s
it would be nice if Todo sections in docstrings where put into an [admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) of some kind rather than ending up in the main description

for example, the following docstring:
```
"""
    validator for pk_select endpoint
    Todo:
        * validate pk_col exists on table
        * validate group_by is a column/list of columns on table
        * validate filter_col exists on table
        * validate dist_table joins to table?
    """
```
end up like so:
![image](https://user-images.githubusercontent.com/15241606/90985203-4578f500-e52f-11ea-824a-41a834dca24c.png)


Discussion:

Patch:
diff --git a/markdown_refdocs/parsers.py b/markdown_refdocs/parsers.py
index 586a383..d4d46e4 100644
--- a/markdown_refdocs/parsers.py
+++ b/markdown_refdocs/parsers.py
@@ -19,6 +19,11 @@ def parse_google_docstring(
 ) -> ParsedDocstring:
     """
     parses a google-style docsting into a dictionary of the various sections
+
+    Args:
+        docstring: the docstring to parse
+        hide_undoc: if True, undocumented arguments will be marked as hidden
+        function_name: name of the function the docstring is for (only used in debugging)
     """
     state = None
     tags = [
@@ -31,6 +36,7 @@ def parse_google_docstring(
         'examples',
         'attributes',
         'warning',
+        'todo',
     ]
     content: Dict[str, Any] = {tag: [] for tag in tags}
 
diff --git a/markdown_refdocs/types.py b/markdown_refdocs/types.py
index cb70fe0..e177b0c 100644
--- a/markdown_refdocs/types.py
+++ b/markdown_refdocs/types.py
@@ -44,6 +44,7 @@ class ParsedDocstring(TypedDict):
     returns: ParsedReturn
     parameters: List[ParsedParameter]
     attributes: List[ParsedParameter]
+    todo: List[str]
 
 
 class ParsedVariable(Parsed):
@@ -65,4 +66,15 @@ class ParsedModule(Parsed):
     variables: List[ParsedVariable]
 
 
-ADMONITIONS = ['warning', 'note', 'info', 'bug', 'tip', 'question', 'failure', 'danger', 'quote']
+ADMONITIONS = [
+    'warning',
+    'note',
+    'info',
+    'bug',
+    'tip',
+    'question',
+    'failure',
+    'danger',
+    'quote',
+    'todo',
+]


Test patch:
diff --git a/tests/test_markdown.py b/tests/test_markdown.py
index 0c059b7..f7e9522 100644
--- a/tests/test_markdown.py
+++ b/tests/test_markdown.py
@@ -1,4 +1,9 @@
-from markdown_refdocs.markdown import constant_to_markdown, create_type_link, function_to_markdown
+from markdown_refdocs.markdown import (
+    constant_to_markdown,
+    create_type_link,
+    function_to_markdown,
+    admonitions_to_markdown,
+)
 
 
 class TestConstantToMarkdown:
@@ -87,3 +92,24 @@ class TestCreateTypeLink:
         types = {'type': link}
         md = create_type_link('Tuple[type, type]', types)
         assert md == f'Tuple\\[[type]({link}), [type]({link})\\]'
+
+
+class TestAdmonitions:
+    def test_todo(self):
+        parsed = {
+            'todo': [
+                '* validate pk_col exists on table',
+                '* validate group_by is a column/list of columns on table',
+                '* validate filter_col exists on table',
+                '* validate dist_table joins to table?',
+            ]
+        }
+
+        expected = """!!! todo
+\t* validate pk_col exists on table
+\t* validate group_by is a column/list of columns on table
+\t* validate filter_col exists on table
+\t* validate dist_table joins to table?
+"""
+        actual = admonitions_to_markdown(parsed)
+        assert actual == expected
diff --git a/tests/test_parsers.py b/tests/test_parsers.py
index 63f16f2..86d0823 100644
--- a/tests/test_parsers.py
+++ b/tests/test_parsers.py
@@ -62,3 +62,24 @@ If the input string is only numbers, return a tuple of (None, {numbers}).
 Otherwise return a tuple of Nones."""
         assert result['description'] == expected
         assert len(result['examples']) == 4
+
+    def test_todo(self):
+        docstring = """
+validator for pk_select endpoint
+Todo:
+    * validate pk_col exists on table
+    * validate group_by is a column/list of columns on table
+    * validate filter_col exists on table
+    * validate dist_table joins to table?
+"""
+        result = parse_google_docstring(docstring)
+
+        expected = [
+            '* validate pk_col exists on table',
+            '* validate group_by is a column/list of columns on table',
+            '* validate filter_col exists on table',
+            '* validate dist_table joins to table?',
+        ]
+
+        for index, line in enumerate(result['todo']):
+            assert line == expected[index]