Extracted subparts of text.mako as separate mako files

docs/templates/pdocs/class.mako

@@ -0,0 +1,109 @@
+<%namespace file="general.mako" import="h1, h2, h3, h4, par"/>
+<%namespace file="table.mako" import="table_rows"/>
+<%namespace file="variable.mako" import="variable"/>
+<%namespace file="function.mako" import="function"/>
+
+##
+## class()
+##
+
+<%def name="class_(cls)" buffered="True">
+${h3(cls.name)}
+
+```python3
+class ${cls.name}(
+    ${",\n    ".join(cls.params())}
+)
+```
+<%
+    cls_pd = cls.parsed_docstring
+    if cls_pd:
+        short_desc = cls_pd.short_description
+        long_desc = cls_pd.long_description
+        params = cls_pd.params
+%>
+
+% if cls_pd:
+    % if short_desc:
+${short_desc}
+
+    % endif
+    %if long_desc:
+${long_desc}
+    % endif
+    % if params:
+${h4("Attributes")}
+
+| Name | Type | Description | Default |
+|---|---|---|---|
+        % for p in params:
+| ${p.arg_name} | ${p.type_name} | ${p.description.replace('\n', '<br>')} | ${p.default} |
+        % endfor
+    % endif
+% else:
+${cls.docstring}
+% endif
+
+% if show_source_code and cls.source:
+
+??? source "View Source"
+        ${"\n        ".join(cls.source)}
+
+------
+
+% endif
+
+<%
+  class_vars = cls.class_variables()
+  static_methods = cls.functions()
+  inst_vars = cls.instance_variables()
+  methods = cls.methods()
+  mro = cls.mro()
+  subclasses = cls.subclasses()
+%>
+% if mro:
+${h4('Ancestors (in MRO)')}
+    % for c in mro:
+* ${c.refname}
+    % endfor
+% endif
+
+% if subclasses:
+${h4('Descendants')}
+    % for c in subclasses:
+* ${c.refname}
+    % endfor
+% endif
+
+% if class_vars:
+${h4('Class variables')}
+    % for v in class_vars:
+${variable(v)}
+
+    % endfor
+% endif
+
+% if static_methods:
+${h4('Static methods')}
+    % for f in static_methods:
+${function(f, True)}
+
+    % endfor
+% endif
+
+% if inst_vars:
+${h4('Instance variables')}
+% for v in inst_vars:
+${variable(v)}
+
+% endfor
+% endif
+% if methods:
+${h4('Methods')}
+% for m in methods:
+${function(m, True)}
+
+% endfor
+% endif
+
+</%def>

docs/templates/pdocs/function.mako

@@ -0,0 +1,133 @@
+<%namespace file="general.mako" import="h1, h2, h3, h4, par"/>
+<%namespace file="table.mako" import="table_rows"/>
+
+<%!
+    IGNORED = None
+    MISSING_STR = ''
+    IGNORE_PARAMS = ['cls', 'self']
+%>
+##
+## function()
+##
+
+<%def name="function(func, class_level=False)" buffered="True">
+    <%
+        formatted_return = func.return_annotation().strip("'")
+        formatted_params = func.params()
+        parsed_ds = func.parsed_docstring
+
+        import inspect
+
+        try:
+            module_name = func.func.__module__ if hasattr(func.func, '__module__') else func.func.__class__.__module__
+            if module_name:
+                import importlib
+                module = importlib.import_module(module_name)
+                globals().update(vars(module))
+                # print(f'Importing: {module_name}')
+
+            signature = inspect.signature(func.func)
+        except (TypeError, ValueError) as e:
+            signature = None
+            print(e)
+
+    %>
+% if class_level:
+${h4(func.name)}
+% else:
+${h3(func.name)}
+% endif
+
+
+``` python3
+def ${func.name}(
+    ${",\n    ".join(formatted_params)}
+)${' -> ' + formatted_return if formatted_return else ''}
+```
+
+% if parsed_ds:
+    <%
+        from docstring_parser import DocstringParam, DocstringReturns
+
+        short_desc = parsed_ds.short_description
+        long_desc = parsed_ds.long_description
+        ds_params = parsed_ds.params
+        ds_returns = parsed_ds.returns
+        raises = parsed_ds.raises
+
+        if signature:
+            ds_params_map = {}
+            for ds_param in ds_params:
+                ds_params_map[ds_param.arg_name] = ds_param
+
+            params = []
+            for name, param in signature.parameters.items():
+                if name in IGNORE_PARAMS:
+                    continue
+
+                description = ''
+                if name in ds_params_map:
+                    description = ds_params_map[name].description
+
+                type_name = get_type_name_from_annotation(param.annotation, param.empty)
+
+                default = param.default if param.default is not param.empty else ''
+
+                params.append(DocstringParam(args=[],
+                                             description=description,
+                                             arg_name=name,
+                                             type_name=type_name,
+                                             is_optional=IGNORED,
+                                             default=default))
+
+            description = ds_returns.description if ds_returns else ''
+
+            type_name = get_type_name_from_annotation(signature.return_annotation, signature.empty)
+
+            if type_name:
+                returns = DocstringReturns(args=[],
+                                           description=description,
+                                           type_name=type_name,
+                                           is_generator=inspect.isgeneratorfunction(func.func),
+                                           return_name=IGNORED)
+            else:
+                returns = None
+
+        else:
+            params = ds_params
+            returns = ds_returns
+    %>
+${par(short_desc)}
+${par(long_desc)}
+    % if params:
+## TODO: Merge params and ret from docstring with func signature, adding missing params, ret and
+##       missing members (e.g. type_name, default)
+
+**Parameters:**
+
+${table_rows(params, show_header=True, show_arg_name=True,
+             show_type=True, show_description=True, show_default=True)}
+    % endif
+    % if returns:
+
+**${"Yields:" if returns.is_generator else "Returns:"}**
+
+${table_rows([returns], show_header=True, show_type=True, show_description=True)}
+    % endif
+    % if raises:
+**Raises:**
+
+${table_rows(raises, show_header=True, show_type=True, show_description=True)}
+    % endif
+% else:
+${func.docstring}
+% endif
+
+% if show_source_code and func.source:
+
+??? source "View Source"
+        ${"\n        ".join(func.source)}
+
+% endif
+</%def>
+

docs/templates/pdocs/general.mako

@@ -0,0 +1,46 @@
+##
+## Disable omnipy root log formatter
+##
+
+<%!
+    from omnipy import runtime
+    runtime.config.root_log.log_format_str = None
+%>
+
+##
+## Constants
+##
+
+<%!
+    IGNORED = None
+    MISSING_STR = ''
+    IGNORE_PARAMS = ['cls', 'self']
+%>
+
+##
+## h1(), h2(), h3(), h4()
+##
+
+<%def name="h1(s)"># ${s}
+</%def>
+
+<%def name="h2(s)">## ${s}
+</%def>
+
+<%def name="h3(s)">### ${s}
+</%def>
+
+<%def name="h4(s)">#### ${s}
+</%def>
+
+
+##
+## par()
+##
+
+<%def name="par(s)">
+% if s:
+${s}
+
+% endif
+</%def>

docs/templates/pdocs/module.mako

@@ -0,0 +1,68 @@
+<%namespace file="general.mako" import="h1, h2, h3, h4, par"/>
+<%namespace file="table.mako" import="table_rows"/>
+<%namespace file="variable.mako" import="variable"/>
+<%namespace file="function.mako" import="function"/>
+<%namespace file="class.mako" import="class_"/>
+
+###
+### Start the output logic for an entire module.
+###
+
+<%
+  variables = module.variables()
+  classes = module.classes()
+  functions = module.functions()
+  submodules = module.submodules
+  heading = 'Namespace' if module.is_namespace else 'Module'
+  parsed_ds = module.parsed_docstring
+%>
+
+${h1(heading + " " + module.name)}
+% if parsed_ds:
+${par(parsed_ds.short_description)}
+${par(parsed_ds.long_description)}
+## TODO: add meta (example and notes)
+% else:
+${module.docstring}
+% endif
+
+${h2("Overview")}
+
+
+% if show_source_code and module.source:
+
+??? source "View Source"
+        ${"\n        ".join(module.source)}
+
+% endif
+
+% if submodules:
+${h2("Sub-modules")}
+    % for m in submodules:
+* [${m.name}](${m.name.split(".")[-1]}/)
+    % endfor
+% endif
+
+% if variables:
+${h2("Variables")}
+    % for v in variables:
+${variable(v)}
+
+    % endfor
+% endif
+
+% if functions:
+${h2("Functions")}
+    % for f in functions:
+${function(f)}
+
+    % endfor
+% endif
+
+% if classes:
+${h2("Classes")}
+    % for c in classes:
+${class_(c)}
+
+    % endfor
+% endif