Merge pull request #604 from AnnMarieW/fix-docstrings

Fix docstrings, reformat reference docs

Author: tcbegley

docs/components_page/api_doc.py

@@ -1,13 +1,12 @@
 import re
 from pathlib import Path
 
+import dash_bootstrap_components as dbc
 import dash_core_components as dcc
 import dash_html_components as html
 import markdown
 
-from .api_doc import ApiDoc
 from .helpers import ExampleContainer, load_source_with_environment
-from .metadata import get_component_metadata
 
 __all__ = ["parse"]
 
@@ -17,6 +16,14 @@
 SPLIT_PATTERN = re.compile(r"{{.*}}")
 EXAMPLE_DOC_PATTERN = re.compile(r"{{(.*)}}")
 
+# To format the docstrings
+VERBATIM_PATTERN = re.compile(r"`((\\\[)((.|\n)*?)(\\]))`")
+LINK_PATTERN = re.compile(r"\\\[([\w\.\-:\/]+)\\\]\(([\w\.\-:#\/]+)\)")
+PROP_OPTIONAL_DEFAULT_PATTERN = re.compile(r"""default (.*)\)""")
+PROP_TYPE_PATTERN = re.compile(r"""(\s*- \w+?\s*\()([^;]*);""")
+PROP_NAME_PATTERN = re.compile(r"""(\n- )(\w+?) \(""")
+NESTED_PROP_NAME_PATTERN = re.compile(r"""(\n\s+- )(\w+?) \(""")
+
 
 def parse(app, markdown_path, extra_env_vars=None):
     extra_env_vars = extra_env_vars or {}
@@ -53,7 +60,9 @@ def _parse_block(block, app, extra_env_vars):
     if type_ == "example":
         return _parse_example(data, app, extra_env_vars)
     elif type_ == "apidoc":
-        return _parse_doc(data)
+        _, filename = data.rsplit("/", 1)
+        component_name = filename[:-3]
+        return component_reference(component_name)
     elif type_ == "code-example":
         return _parse_code_example(data)
     raise ValueError("Unable to parse block.")
@@ -92,15 +101,43 @@ def _parse_code_example(data):
     )
 
 
-def _parse_doc(data):
-    _, filename = data.rsplit("/", 1)
-    return ApiDoc(get_component_metadata(data), component_name=filename[:-3])
-
-
 def _interleave(l1, l2):
     n = len(l2)
     out = []
     for x in zip(l1[:n], l2):
         out.extend(x)
     out.extend(l1[n:])
     return out
+
+
+def component_reference(component_name):
+    component = getattr(dbc, component_name)
+    component_doc = component.__doc__
+
+    return_div = [
+        dcc.Markdown("### Keyword arguments for {}".format(component_name))
+    ]
+
+    docs = component_doc.split("Keyword arguments:")[-1]
+
+    docs = re.sub(VERBATIM_PATTERN, r"`[\3]`", docs)
+    # format links
+    docs = re.sub(LINK_PATTERN, r"[\1](\2)", docs)
+
+    # formats the prop defaults
+    docs = re.sub(PROP_OPTIONAL_DEFAULT_PATTERN, r"default `\1`)", docs)
+
+    # formats the prop type
+    docs = re.sub(PROP_TYPE_PATTERN, r"\1*\2*;", docs)
+
+    # formats the prop name on first level only
+    docs = re.sub(PROP_NAME_PATTERN, r"\1**`\2`** (", docs)
+
+    # formats keys of nested dicts
+    docs = re.sub(NESTED_PROP_NAME_PATTERN, r"\1**`\2`** (", docs)
+
+    # removes a level of nesting
+    docs = docs.replace("\n-", "\n")
+
+    return_div.append(dcc.Markdown(docs))
+    return html.Div(return_div, className="reference")

docs/components_page/markdown_parser.py

@@ -48,7 +48,7 @@
     "jest": "^24.9.0",
     "npm-run-all": "^4.1.5",
     "prettier": "^1.19.1",
-    "react-docgen": "^2.21.0",
+    "react-docgen": "^4.1.1",
     "style-loader": "^0.23.1",
     "webpack": "^4.44.1",
     "webpack-cli": "^3.3.12",