Skip to content

Conversation

c-herrewijn
Copy link
Member

@c-herrewijn c-herrewijn commented Mar 10, 2025

This PR adds a script to update sql function doc pages based on the output of duckdb_functions().
Page docs/sql/functions/blob.md was created to show its functionality, and uses the category labels introduced in duckdb/duckdb#15654

Dependencies

  • script generate_sql_function_docs.py requires a duckdb version that includes PR 15654, which introduces the 'categories' label to the output of duckdb_functions(). (not yet merged as of now)

Settings

script generate_sql_function_docs.py has a number of hard coded settings that will probably change or move to a config file in the future:

  • DOC_CATEGORY_MAP - lists which doc pages will be generated, and which category from duckdb_functions() applies
  • BINARY_OPERATORS - lists 'functions' that are binary operators, which are listed between the arguments
  • OVERRIDES_MAP - hardcoded overrides and additions relative to the duckdb_functions() outputs:
    • for now: use for table_functions / macros, since they are not yet covered by duckdb_functions()
    • use for functions (like ||) that use parameter_types = ANY. (Ideally these functions should be implemented as a ScalarFunctionSet, so the supported function overloads can be explicitly outputted by duckdb_functions()
  • URL_CONVERSIONS - adds url links to the function descriptions, as they are not present in the duckdb_functions() output
  • FIXED_EXAMPLES - contains fixed example results, for examples that can not be run independently (e.g. because they are dependent on an input file or the existence of specific data tables)

Limitations

  • alias information is not yet available in the output of duckdb_functions(), so is currently missing from generated doc pages
  • table functions and macros can only be added manually via OVERRIDES_MAP, since they are not properly listed by duckdb_functions()
  • displaying multiple examples is currently not supported, even though this information is available via duckdb_functions()

@szarnyasg
Copy link
Collaborator

Thanks!

@szarnyasg szarnyasg merged commit 3face21 into duckdb:main Mar 25, 2025
4 checks passed
@c-herrewijn c-herrewijn deleted the generate_sql_function_docs branch March 28, 2025 11:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants