Add function/target documentation based on Sphinx/Jinja2. Replace command line function listings by hyperlink

Author: mlell

README.rst

@@ -5,3 +5,18 @@ beanquery is a customizable and extensible lightweight SQL query tool
 that works on tabular data, including `Beancount`__ ledger data.
 
 __ https://beancount.github.io/
+
+With this tool you can write *queries* to extract information from your
+Beancount ledger. This is the documentation of functions and field names
+which are available for queries. 
+
+Please read the Manual of the `Beancount Query Language (BQL)`__ if you
+do not yet know how to write queries.
+
+
+__ http://furius.ca/beancount/doc/query
+
+After you have learned the BQL, you can use the 
+`list and documentation of available functions and columns`__
+
+__ https://beancount.github.io/beanquery

beanquery/query_compile.py

@@ -406,14 +406,26 @@ def __call__(self, context):
 
 
 class EvalFunction(EvalNode):
+    """Base class for function evaluation nodes.
+    
+    Class Attributes:
+        __intypes__: List of input parameter types for type checking.
+        __outtype__: Output type of the function. None means no type 
+          annotation. To annotate that the function returns None, use
+          types.NoneType.
+        __param_names__: List of argument names.
+    """
     __slots__ = ('operands',)
-
+    
     # Type constraints on the input arguments.
     __intypes__ = []
 
     # Output type annotation
     __outtype__ = None
 
+    # Input argument names for documentation.
+    __param_names__ = []
+    
     def __init__(self, context, operands, dtype):
         super().__init__(dtype)
         self.context = context

beanquery/query_env.py

@@ -79,11 +79,7 @@ def _extract_param_names(func):
     """
     sig = inspect.signature(func)
     param_names = list(sig.parameters.keys())
-    
-    # Remove 'self' if present (for class methods)
-    if param_names and param_names[0] == 'self':
-        param_names = param_names[1:]
-    
+
     return param_names
 
 
@@ -154,6 +150,8 @@ def __call__(self, row):
         Func.__name__ = name if name is not None else func.__name__
         Func.__doc__ = func.__doc__
         query_compile.FUNCTIONS[Func.__name__].append(Func)
+        _add_to_doc_groups(Func, intypes, groups)
+        
         return func
     return decorator
 
@@ -169,15 +167,14 @@ def register(name=None, groups=None):
            TYPE_CATEGORIES for valid group names.
     """
     def decorator(cls):
-        # Extract parameter names from __init__ method, excluding 'self'
-        param_names = cls.__param_names__
         # Remove the context parameter
-        param_names = param_names[1:]
-        
+        cls.__param_names__ = cls.__param_names__[1:]
+
         if name is not None:
             cls.__name__ = name
-        cls.__param_names__ = param_names
         query_compile.FUNCTIONS[cls.__name__].append(cls)
+        _add_to_doc_groups(cls, cls.__intypes__, groups)
+        
         return cls
     return decorator
 
@@ -861,11 +858,7 @@ def interval(x):
 
 @function([relativedelta, datetime.date, datetime.date], datetime.date, groups = ['date'])
 def date_bin(stride, source, origin):
-    """Bin a date into the specified stride aligned with the specified origin.
 
-    As an extension to the the SQL standard ``date_bin()`` function this
-    function also accepts strides containing units of months and years.
-    """
     if stride.months or stride.years:
         if origin + stride <= origin:
             # FIXME: this should raise and error: stride must be greater than zero
@@ -1071,3 +1064,57 @@ def update(self, store, context):
             cur = store[self.handle]
             if cur is None or value > cur:
                 store[self.handle] = value
+
+def _describe_functions(functions, aggregates=False, type_filter=None):
+    """Describe functions, optionally filtered by input type category.
+
+    Args:
+        functions: Dictionary of (function name: EvalFunction subclass),
+          the actual class, not an object, which would represent a particular
+          function call.
+        aggregates: If True, show aggregates; if False, show regular functions
+        type_filter: Optional filter by input type category (see TYPE_CATEGORIES)
+    """
+    # Determine which functions to iterate over
+    if type_filter:
+        # Use the pre-populated FUNCTION_DOC_GROUPS for filtering
+        funcs_to_process = FUNCTION_DOC_GROUPS.get(type_filter, [])
+    else:
+        # Collect all functions from all groups
+        funcs_to_process = []
+        for name, funcs in functions.items():
+            funcs_to_process.extend(funcs)
+    
+    entries = []
+    for func in funcs_to_process:
+        # Filter by aggregate vs non-aggregate
+        if aggregates != issubclass(func, query_compile.EvalAggregator):
+            continue
+        
+        # Get the function name
+        name = func.__name__.lower()
+        
+        # Assemble function signature for output using parameter names
+        args = ', '.join(f'{param_name}: {types.name(dtype)}'
+                        for param_name, dtype in zip(func.__param_names__, func.__intypes__))
+        
+        if func.__outtype__:
+            outtype = types.name(func.__outtype__)
+        else:
+            outtype = None
+        
+        doc = func.__doc__ or ''
+        entries.append((name, doc, args, outtype))
+    
+    entries.sort()
+    return entries
+
+def _format_description(entries):
+    out = io.StringIO()
+    wrapper = textwrap.TextWrapper(initial_indent='  ', subsequent_indent='  ', width=80)
+    for key, entries in itertools.groupby(entries, key=lambda x: x[:2]):  # noqa: B020
+        for name, doc, args, outtype in entries:
+            print(f'{name}({args}) -> {outtype}', file=out)
+        print(wrapper.fill(re.sub(r'[ \n\t]+', ' ', doc or '')), file=out)
+        print(file=out)
+    return out.getvalue().rstrip()

beanquery/shell.py

@@ -629,69 +629,50 @@ def help_targets(self):
         template = textwrap.dedent("""
 
           The list of comma-separated target expressions may consist of columns,
-          simple functions and aggregate functions. If you use any aggregate
-          function, you must also provide a GROUP-BY clause.
+          simple functions and aggregate functions. You can use AS to determine
+          the output column name, for example:
 
-          Columns
-          -------
+              SELECT yearmonth(date) AS month ....
 
-          {columns}
+          If you use any aggregate function, you must also provide a GROUP-BY
+          clause.
 
-          Functions
-          ---------
+          See the online Beanquery documentation for the full list of columns,
+          functions, and aggregates:
 
-          {functions}
-
-          Aggregate functions
-          -------------------
-
-          {aggregates}
+              https://beancount.github.io/beanquery/
 
         """)
-        print(template.format(**_describe(self.context.tables['postings'],
-                                          query_compile.FUNCTIONS)), file=self.outfile)
+
+        print(template, file=self.outfile)
 
     def help_from(self):
         template = textwrap.dedent("""
 
           A logical expression that consist of columns on directives (mostly
           transactions) and simple functions.
 
-          Columns
-          -------
-
-          {columns}
-
-          Functions
-          ---------
+          See the online Beanquery documentation for the full list of columns,
+          functions, and aggregates:
 
-          {functions}
+              https://beancount.github.io/beanquery/
 
         """)
-        print(template.format(**_describe(self.context.tables['entries'],
-                                          query_compile.FUNCTIONS)),
-              file=self.outfile)
+        print(template, file=self.outfile)
 
     def help_where(self):
         template = textwrap.dedent("""
 
           A logical expression that consist of columns on postings and simple
           functions.
 
-          Columns
-          -------
+          See the online Beanquery documentation for the full list of columns,
+          functions, and aggregates:
 
-          {columns}
-
-          Functions
-          ---------
-
-          {functions}
+              https://beancount.github.io/beanquery/
 
         """)
-        print(template.format(**_describe(self.context.tables['postings'],
-                                          query_compile.FUNCTIONS)), file=self.outfile)
-
+        print(template, file=self.outfile)
 
 def _describe_columns(columns):
     out = io.StringIO()
@@ -702,35 +683,6 @@ def _describe_columns(columns):
         print(file=out)
     return out.getvalue().rstrip()
 
-
-def _describe_functions(functions, aggregates=False):
-    entries = []
-    for name, funcs in functions.items():
-        if aggregates != issubclass(funcs[0], query_compile.EvalAggregator):
-            continue
-        name = name.lower()
-        for func in funcs:
-            args = ', '.join(types.name(d) for d in func.__intypes__)
-            doc = re.sub(r'[ \n\t]+', ' ', func.__doc__ or '')
-            entries.append((name, doc, args))
-    entries.sort()
-    out = io.StringIO()
-    wrapper = textwrap.TextWrapper(initial_indent='  ', subsequent_indent='  ', width=80)
-    for key, entries in itertools.groupby(entries, key=lambda x: x[:2]):  # noqa: B020
-        for name, doc, args in entries:
-            print(f'{name}({args})', file=out)
-        print(wrapper.fill(doc), file=out)
-        print(file=out)
-    return out.getvalue().rstrip()
-
-
-def _describe(table, functions):
-    return dict(
-        columns=_describe_columns(table.columns),
-        functions=_describe_functions(functions, aggregates=False),
-        aggregates=_describe_functions(functions, aggregates=True))
-
-
 def summary_statistics(entries):
     """Calculate basic summary statistics to output a brief welcome message.
 

beanquery/sources/beancount.py

@@ -104,6 +104,13 @@ class Position(types.Structure):
 
 
 class Cost(types.Structure):
+    """The amount which was payed for a position. This object
+    saves besides the amount also the date and label (if assigned).
+    This serves to identify the position to sell according to
+    a `given booking rule`__.
+
+    __ https://beancount.github.io/docs/beancount_language_syntax.html#reducing-positions
+    """
     name = 'cost'
     columns = _typed_namedtuple_to_columns(data.Cost)
 
@@ -296,7 +303,8 @@ def id(entry):
 
     @columns.register(str)
     def type(entry):
-        """The data type of the directive."""
+        """The data type of the directive. Currently, beanquery only can list
+        the directives of type 'transaction'."""
         return type(entry).__name__.lower()
 
     @columns.register(str)

docs/bql_functions.rst.j2

@@ -0,0 +1,58 @@
+List of all BQL Functions
+==========================
+
+This page documents all available BQL functions.
+
+..
+    Disambiguate functions and types by pretending they are in 
+    different modules (we are documenting BQL with the Sphinx Python
+    domain). We put functions in the virtual module "fun" (thus
+    functions must be explicitly linked like :func:`~fun.myfunction`).
+    Types have no module such that they are auto-linked by the 
+    `.. function:` directives.
+
+.. currentmodule:: fun
+
+{# Render documentation for all functions. This uses the function docstrings
+defined in beancount/query_env.py. There are multiple variants of many functions,
+differing in the type and number of arguments. We group the variants which
+have the same docstrings to render them en bloc. If all variants of a function
+of a certain name have the same docstring, we list all signatures directly in
+the RST function:: directive. Otherwise, we write .. function:: myfunction(...) 
+and render code blocks with the signatures, followed by the documentation for
+this group of variants.
+#}
+{% macro render_functions(functions) %}
+{% for name, args, has_multiple_docs, docs in preprocess_function_documentation(functions) %}
+{% if has_multiple_docs %}
+.. function:: {{ name }}(...)
+
+{% for variant in docs %}
+  ::
+
+    {{ variant.signatures }}
+
+{{ variant.doc_text | indent(2, first=True) }}
+
+{% endfor %}
+{% else %}
+.. function::
+{% for sig in args %}
+   {{ sig }}
+{% endfor %}
+
+{{ docs | indent(2, first=True) }}
+
+{% endif %}
+{% endfor %}
+{% endmacro %}
+
+Simple functions
+----------------
+
+{{ render_functions(_describe_functions(FUNCTIONS)) }}
+
+Aggregation functions
+---------------------
+
+{{ render_functions(_describe_functions(FUNCTIONS, aggregates=True)) }}

docs/columns_entry.rst.j2

@@ -0,0 +1,14 @@
+Targets: Entry
+==============
+
+This is the list of all the fields you can use in the 
+SELECT ... clause and the FROM ... clause of a BQL query.
+
+For available functions and aggregates to use with these 
+columns, see :doc:`functions_index`.
+
+{% for name, type_name, doc in preprocess_targets(EntriesTable) -%}
+* **{{ name }}**: ({{ type_name }}) {{ doc }}
+
+{% endfor %}
+

docs/columns_postings.rst.j2

@@ -0,0 +1,14 @@
+Fields: Posting
+===============
+
+This is the list of all the fields you can use in the 
+WHERE ... clause of a BQL query.
+
+For available functions and aggregates to use with these 
+columns, see :doc:`functions_index`.
+
+{% for name, type_name, doc in preprocess_targets(PostingsTable) -%}
+* **{{ name }}**: ({{ type_name }}) {{ doc }}
+
+{% endfor %}
+