|
| 1 | +from docutils.parsers.rst import Directive, directives |
| 2 | +from docutils import nodes |
| 3 | +import importlib |
| 4 | +import inspect |
| 5 | +import docstring_parser |
| 6 | + |
| 7 | + |
| 8 | +DEFAULT_DOCSTRING = """ |
| 9 | +Default configuration for pyopenms_viz |
| 10 | +
|
| 11 | +Attributes: |
| 12 | + x (str): The column name for the X-axis data. Required. |
| 13 | + y (str): The column name for the Y-axis data. Required. |
| 14 | + by (str): The column name for the grouping variable. |
| 15 | + canvas (Any): Canvas for the plot. For Bokeh, this is a bokeh.plotting.Figure object. For Matplotlib, this is an Axes object, and for Plotly, this is a plotly.graph_objects.Figure object. If none, axis will be created Defaults to None. |
| 16 | + show_plot (bool): Whether to display the plot. Defaults to True. |
| 17 | +""" |
| 18 | + |
| 19 | + |
| 20 | +class DocstringToTableDirective(Directive): |
| 21 | + has_content = False |
| 22 | + required_arguments = 0 |
| 23 | + optional_arguments = 0 |
| 24 | + option_spec = { |
| 25 | + "docstring": str, |
| 26 | + "title": str, |
| 27 | + "parent_depth": int, # Number of parent classes to include |
| 28 | + "default_docstring": directives.flag, # Flag, no argument required |
| 29 | + } |
| 30 | + |
| 31 | + def run(self): |
| 32 | + docstring_path = self.options.get("docstring") |
| 33 | + table_title = self.options.get("title") |
| 34 | + # If parent_depth is not specified, only include the base class (depth=0) |
| 35 | + parent_depth = self.options.get("parent_depth") |
| 36 | + if parent_depth is None: |
| 37 | + parent_depth = 0 |
| 38 | + else: |
| 39 | + parent_depth = int(parent_depth) |
| 40 | + if not docstring_path: |
| 41 | + error = self.state_machine.reporter.error( |
| 42 | + "No :docstring: option provided to docstring_to_table directive.", |
| 43 | + line=self.lineno, |
| 44 | + ) |
| 45 | + return [error] |
| 46 | + |
| 47 | + # Split module and object |
| 48 | + mod_name, _, obj_path = docstring_path.partition(".") |
| 49 | + if not obj_path: |
| 50 | + error = self.state_machine.reporter.error( |
| 51 | + f"Invalid docstring path: {docstring_path}", line=self.lineno |
| 52 | + ) |
| 53 | + return [error] |
| 54 | + |
| 55 | + # Import module and get object |
| 56 | + try: |
| 57 | + mod = importlib.import_module(mod_name) |
| 58 | + obj = mod |
| 59 | + for attr in docstring_path.split(".")[1:]: |
| 60 | + obj = getattr(obj, attr) |
| 61 | + except Exception as e: |
| 62 | + error = self.state_machine.reporter.error( |
| 63 | + f"Could not import object '{docstring_path}': {e}", line=self.lineno |
| 64 | + ) |
| 65 | + return [error] |
| 66 | + |
| 67 | + # Collect docstrings from parent classes up to parent_depth |
| 68 | + docstrings = [] |
| 69 | + current_obj = obj |
| 70 | + for i in range(parent_depth + 1): |
| 71 | + docstring = inspect.getdoc(current_obj) |
| 72 | + if docstring: |
| 73 | + docstrings.append(docstring) |
| 74 | + bases = getattr(current_obj, "__bases__", ()) |
| 75 | + if bases and i < parent_depth: |
| 76 | + current_obj = bases[0] |
| 77 | + else: |
| 78 | + break |
| 79 | + |
| 80 | + # Parse all collected docstrings |
| 81 | + params = [] |
| 82 | + param_names = [] |
| 83 | + # If :default_docstring: is present (flag), prepend its params |
| 84 | + if "default_docstring" in self.options: |
| 85 | + default_parsed = docstring_parser.parse(DEFAULT_DOCSTRING) |
| 86 | + for param in default_parsed.params: |
| 87 | + name = param.arg_name or "" |
| 88 | + default = param.default or "" |
| 89 | + typ = param.type_name or "" |
| 90 | + desc = param.description or "" |
| 91 | + if not default: |
| 92 | + name = f"{name}*" |
| 93 | + params.append((name, typ, desc, default)) |
| 94 | + for docstring in reversed(docstrings): # Start from base class |
| 95 | + parsed = docstring_parser.parse(docstring) |
| 96 | + for param in parsed.params: |
| 97 | + name = param.arg_name or "" |
| 98 | + default = param.default or "" |
| 99 | + typ = param.type_name or "" |
| 100 | + desc = param.description or "" |
| 101 | + # Mark required parameters (no default) with '*' |
| 102 | + if not default: |
| 103 | + name_out = f"{name}*" |
| 104 | + else: |
| 105 | + name_out = name |
| 106 | + # Only keep the most "child" definition of each parameter |
| 107 | + if name in param_names: |
| 108 | + # Find and remove the old parameter from the list |
| 109 | + # It could be with or without a star |
| 110 | + for i, (p_name, _, _, _) in enumerate(params): |
| 111 | + if p_name.strip("*") == name: |
| 112 | + params.pop(i) |
| 113 | + break |
| 114 | + params.append((name_out, typ, desc, default)) |
| 115 | + if name not in param_names: |
| 116 | + param_names.append(name) |
| 117 | + |
| 118 | + # Build table |
| 119 | + table = nodes.table() |
| 120 | + if table_title: |
| 121 | + title_node = nodes.title(text=table_title) |
| 122 | + table += title_node |
| 123 | + tgroup = nodes.tgroup(cols=4) |
| 124 | + table += tgroup |
| 125 | + for width in [1, 1, 3, 1]: |
| 126 | + tgroup += nodes.colspec(colwidth=width) |
| 127 | + thead = nodes.thead() |
| 128 | + tgroup += thead |
| 129 | + header_row = nodes.row() |
| 130 | + for h in ["Parameter", "Type", "Description", "Default"]: |
| 131 | + entry = nodes.entry() |
| 132 | + entry += nodes.paragraph(text=h) |
| 133 | + header_row += entry |
| 134 | + thead += header_row |
| 135 | + tbody = nodes.tbody() |
| 136 | + tgroup += tbody |
| 137 | + for param in params: |
| 138 | + row = nodes.row() |
| 139 | + for cell in param: |
| 140 | + entry = nodes.entry() |
| 141 | + entry += nodes.paragraph(text=cell) |
| 142 | + row += entry |
| 143 | + tbody += row |
| 144 | + return [table] |
| 145 | + |
| 146 | + |
| 147 | +def setup(app): |
| 148 | + app.add_directive("docstring_to_table", DocstringToTableDirective) |
0 commit comments