Improve function help by grouping by function type

[mlell]

As someone new to beancount, I found the function documentation really hard to navigate. The old help functions dumped everything on screen at once, which was overwhelming. While developing a BQL query, I found myself looking for functions to transform certain argument types, however I just had an alphabetical function list. (Re-open of #262)

What I changed:

Progressive disclosure:

• help functions now shows just a category overview (takes ~10 lines instead of 100+) and explains custom object types
• help functions amount shows only amount-related functions, same for date, position, atomic,...

Better function docs:

• Added argument explanations to some functions (the old docs assumed you knew what arguments meant)
• Example: grep(pattern, string) now explains "pattern" is a regex and "string" is input text
• Examples on some types, e.g. Position is something like 10 HOOL {100.30 USD}

Technical implementation:

• Query functions are grouped according to their first argument's type by _describe_function().
• In addition, the decorators @function, @register and @aggregator take a group= argument to refine (e.g. for account names, which are strings)

The main benefit is you can find functions now much easier without scrolling through pages of text. When I started with beancount, I had no idea what functions were available or how to use them - I hope this makes it easier.

[dnicolodi]

Thanks for looking into improving the help system. I only went very quickly through the changes, but I feel that most of what you add some come in the form of documentation rather than in form of verbose help commands. Quite a few functions are deprecated and should be hidden from the help completely (or by default, or at least clearly marked as deprecated).

[mlell]

I am not sure I understand your point, did you mean: "I feel that most of what you add should come in the form of documentation..."? I would be happy to help with the documentation, however, at least in the beancount docs the help commands were mentioned as the location for function documentation, so I have amended those commands. Can you point me to where to add such information?

[mlell]

@dnicolodi Hi, I was just wondering if there is anything I could do to move this forward. I find this tool very useful and would lovehto help improve it!

[dnicolodi]

Yes, sorry, typo: I meant that about all of this should be added as documentation. The inline help should be improved somehow, but I would not go beyond providing argument names. The description of the functions should be provided in the manual. It could be an idea to have links from the inline help to the online manual in terminals that support hyperlinks.

There is currently only a placeholder for the documentation https://github.com/beancount/beanquery/tree/master/docs I haven't found resources to work on it. Feel free to start adding content there and submit PRs.

[mlell]

Please check https://mlell.github.io/beanquery for a preview of the function documentation. I have:

• Extended EvalFunction so that output type annotation is not only confined to @function (query_env.py),
  but also available for @register and @aggregator.
• Kept the function grouping to have both an alphabetic list as well as type-specific lists
• Created a function and type documentation based on Sphinx and Jinja2 templates, added an
  utility script in docs/ which renders the Jinja2 templates to RST files and calls sphinx-build.
  It uses information supplied by the helper function _describe_functions. This is now moved
  to query_env.py, because
• The command-line help does not show the full function list anymore, to save screen space.
  Instead, it provides the hyperlink to the online docs, which is much nicer to navigate in than
  the previous text dump to the terminal when doing .help targets or .help from.

[mlell]

Failing ruff checks about unused variables after unpacking tuples are not related to my code:

RUF059 Unpacked variable `atypes` is never used
   --> beanquery/numberify_test.py:133:9
RUF059 Unpacked variable `columns` is never used
   --> beanquery/query_compile.py:590:9
RUF059 Unpacked variable `columns` is never used
   --> beanquery/query_compile.py:604:13
RUF059 Unpacked variable `columns` is never used
   --> beanquery/query_compile.py:704:13
RUF059 Unpacked variable `rtypes` is never used
  --> beanquery/query_env_test.py:64:9
RUF059 Unpacked variable `rtypes` is never used
   --> beanquery/query_env_test.py:98:9
RUF059 Unpacked variable `rtypes` is never used
   --> beanquery/query_env_test.py:121:9
RUF059 Unpacked variable `rtypes` is never used
   --> beanquery/query_env_test.py:144:9
RUF059 Unpacked variable `rtypes` is never used
   --> beanquery/query_env_test.py:164:9
RUF059 Unpacked variable `nullable` is never used
  --> beanquery/sources/beancount.py:91:16
RUF059 Unpacked variable `index` is never used
   --> beanquery/sources/beancount.py:286:22

Found 12 errors.
No fixes available (12 hidden fixes can be enabled with the `--unsafe-fixes` option).
Error: Process completed with exit code 1.