WIP apidocs

Author: ceteri

docs/mkrefs.yml

@@ -1,7 +1,7 @@
 apidocs:
   page: ref.md
   template: ref.jinja
-  module: mkrefs
+  package: mkrefs
   git: https://github.com/DerwenAI/mkrefs/blob/main
   includes: MkRefsPlugin, PackageDoc
 

mkrefs/apidocs.py

@@ -51,42 +51,50 @@ class PackageDoc:
 
     def __init__ (
         self,
-        module_name: str,
+        package_name: str,
         git_url: str,
         class_list: typing.List[str],
         ) -> None:
         """
 Constructor, to configure a `PackageDoc` object.
 
-    module_name:
-name of the Python module
+    package_name:
+name of the Python package
 
     git_url:
 URL for the Git source repository
 
     class_list:
 list of the classes to include in the apidocs
         """
-        self.module_name = module_name
+        self.package_name = package_name
         self.git_url = git_url
         self.class_list = class_list
 
-        module_obj = importlib.import_module(self.module_name)
-        self.module_obj = sys.modules[self.module_name]
+        package_obj = importlib.import_module(self.package_name)
+        self.package_obj = sys.modules[self.package_name]
 
         self.md: typing.List[str] = [
-            "# Reference: `{}` package".format(self.module_name),
+            "# Reference: `{}` package".format(self.package_name),
             ]
 
+        self.meta = {
+            "package": self.package_name,
+            "git_url": self.git_url,
+            "class": {},
+            "function": {},
+            "type": {},
+        }
+
 
     def show_all_elements (
         self
         ) -> None:
         """
-Show all possible elements from `inspect` for the given module, for
+Show all possible elements from `inspect` for the given package, for
 debugging purposes.
         """
-        for name, obj in inspect.getmembers(self.module_obj):
+        for name, obj in inspect.getmembers(self.package_obj):
             for n, o in inspect.getmembers(obj):
                 ic(name, n, o)
                 ic(type(o))
@@ -96,14 +104,14 @@ def get_todo_list (
         self
         ) -> typing.Dict[ str, typing.Any]:
         """
-Walk the module tree to find class definitions to document.
+Walk the package tree to find class definitions to document.
 
     returns:
 a dictionary of class objects which need apidocs generated
         """
         todo_list: typing.Dict[ str, typing.Any] = {
             class_name:  class_obj
-            for class_name, class_obj in inspect.getmembers(self.module_obj, inspect.isclass)
+            for class_name, class_obj in inspect.getmembers(self.package_obj, inspect.isclass)
             if class_name in self.class_list
             }
 
@@ -118,8 +126,11 @@ def build (
         """
         todo_list: typing.Dict[ str, typing.Any] = self.get_todo_list()
 
-        # markdown for top-level module description
-        self.md.extend(self.get_docstring(self.module_obj))
+        # markdown for top-level package description
+        docstring = self.get_docstring(self.package_obj)
+        self.md.extend(docstring)
+
+        self.meta["docstring"] = docstring
 
         # find and format the class definitions
         for class_name in self.class_list:
@@ -230,7 +241,7 @@ def fix_fwd_refs (
         anno: str,
         ) -> typing.Optional[str]:
         """
-Substitute the quoted forward references for a given module class.
+Substitute the quoted forward references for a given package class.
 
     anno:
 raw annotated type for the forward reference
@@ -257,6 +268,7 @@ def document_method (
         name: str,
         obj: typing.Any,
         func_kind: str,
+        func_meta: dict,
         ) -> typing.Tuple[int, typing.List[str]]:
         """
 Generate apidocs markdown for the given class method.
@@ -273,6 +285,9 @@ class method object
     func_kind:
 function kind
 
+    func_meta:
+function metadata
+
     returns:
 line number, plus apidocs for the method as a list of markdown lines
         """
@@ -283,6 +298,8 @@ class method object
         anchor = "#### [`{}` {}](#{})".format(name, func_kind, frag)
         local_md.append(anchor)
 
+        func_meta["ns_path"] = frag
+
         # link to source code in Git repo
         code = obj.__code__
         line_num = code.co_firstlineno
@@ -291,6 +308,8 @@ class method object
         src_url = "[*\[source\]*]({}{}#L{})\n".format(self.git_url, file, line_num)  # pylint: disable=W1401
         local_md.append(src_url)
 
+        func_meta["line_num"] = line_num
+
         # format the callable signature
         sig = inspect.signature(obj)
         arg_list = self.get_arg_list(sig)
@@ -300,6 +319,8 @@ class method object
         local_md.append("{}({})".format(name, arg_list_str))
         local_md.append("```")
 
+        func_meta["arg_list_str"] = arg_list_str
+
         # include the docstring, with return annotation
         arg_dict: dict = {
             name.split("=")[0]: anno
@@ -313,9 +334,13 @@ class method object
         if ret:
             arg_dict["returns"] = self.extract_type_annotation(ret)
 
-        local_md.extend(self.get_docstring(obj, parse=True, arg_dict=arg_dict))
+        arg_docstring = self.get_docstring(obj, parse=True, arg_dict=arg_dict)
+        local_md.extend(arg_docstring)
         local_md.append("")
 
+        func_meta["arg_dict"] = arg_dict
+        func_meta["arg_docstring"] = arg_docstring
+
         return line_num, local_md
 
 
@@ -419,17 +444,24 @@ def document_type (
         """
         local_md: typing.List[str] = []
 
+        type_meta = {}
+        self.meta["type"][name] = type_meta
+
         # format a header + anchor
         frag = ".".join(path_list + [ name ])
         anchor = "#### [`{}` {}](#{})".format(name, "type", frag)
         local_md.append(anchor)
 
+        type_meta["ns_path"] = frag
+
         # show type definition
         local_md.append("```python")
         local_md.append("{} = {}".format(name, obj))
         local_md.append("```")
         local_md.append("")
 
+        type_meta["obj"] = obj
+
         return local_md
 
 
@@ -482,14 +514,21 @@ class object
         docstring = class_obj.__doc__
         src = inspect.getsourcelines(class_obj)
 
+        class_meta = {
+            "docstring": docstring,
+            "method": {},
+            }
+
+        self.meta["class"][class_name] = class_meta
+
         if docstring:
             # add the raw docstring for a class
             self.md.append(docstring)
 
         obj_md_pos: typing.Dict[int, typing.List[str]] = {}
 
         for member_name, member_obj in inspect.getmembers(class_obj):
-            path_list = [self.module_name, class_name]
+            path_list = [self.package_name, class_name]
 
             if member_name.startswith("__") or not member_name.startswith("_"):
                 if member_name not in class_obj.__dict__:
@@ -503,7 +542,10 @@ class object
                 else:
                     continue
 
-                _, obj_md = self.document_method(path_list, member_name, member_obj, func_kind)
+                func_meta = {}
+                class_meta["method"][member_name] = func_meta
+
+                _, obj_md = self.document_method(path_list, member_name, member_obj, func_kind, func_meta)
                 line_num = self.find_line_num(src, member_name)
                 obj_md_pos[line_num] = obj_md
 
@@ -515,32 +557,35 @@ def format_functions (
         self
         ) -> None:
         """
-Walk the module tree, and for each function definition format its
+Walk the package tree, and for each function definition format its
 apidocs as markdown.
         """
         self.md.append("---")
-        self.md.append("## [module functions](#{})".format(self.module_name))
+        self.md.append("## [package functions](#{})".format(self.package_name))
 
-        for func_name, func_obj in inspect.getmembers(self.module_obj, inspect.isfunction):
+        for func_name, func_obj in inspect.getmembers(self.package_obj, inspect.isfunction):
             if not func_name.startswith("_"):
-                _, obj_md = self.document_method([self.module_name], func_name, func_obj, "function")
+                func_meta = {}
+                self.meta["function"][func_name] = func_meta
+
+                _, obj_md = self.document_method([self.package_name], func_name, func_obj, "function", func_meta)
                 self.md.extend(obj_md)
 
 
     def format_types (
         self
         ) -> None:
         """
-Walk the module tree, and for each type definition format its apidocs
+Walk the package tree, and for each type definition format its apidocs
 as markdown.
         """
         self.md.append("---")
-        self.md.append("## [module types](#{})".format(self.module_name))
+        self.md.append("## [package types](#{})".format(self.package_name))
 
-        for name, obj in inspect.getmembers(self.module_obj):
+        for name, obj in inspect.getmembers(self.package_obj):
             if obj.__class__.__module__ == "typing":
                 if not str(obj).startswith("~"):
-                    obj_md = self.document_type([self.module_name], name, obj)
+                    obj_md = self.document_type([self.package_name], name, obj)
                     self.md.extend(obj_md)
 
 
@@ -565,7 +610,7 @@ def render_apidocs (  # pylint: disable=R0914
     returns:
 rendered Markdown
     """
-    module_name = local_config["apidocs"]["module"]
+    package_name = local_config["apidocs"]["package"]
     git_url = local_config["apidocs"]["git"]
 
     includes = [
@@ -574,7 +619,7 @@ def render_apidocs (  # pylint: disable=R0914
     ]
 
     pkg_doc = PackageDoc(
-        module_name,
+        package_name,
         git_url,
         includes,
         )

mkrefs/plugin.py

@@ -41,7 +41,7 @@ class MkRefsPlugin (mkdocs.plugins.BasePlugin):
         "apidocs": {
             "page": "the generated Markdown page; e.g., `ref.md`",
             "template": "a Jinja2 template; e.g., `ref.jinja`",
-            "module": "module name for the package",
+            "package": "the Python package name",
             "git": "URL to the source code in a public Git repository",
             "includes": "class and function names to include",
             },