Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate sql function docs #4583

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

c-herrewijn
Copy link
Contributor

@c-herrewijn c-herrewijn commented Jan 15, 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 PR 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()

@c-herrewijn
Copy link
Contributor Author

linting issue dependent on bump of black version, to support python 3.12 functionality
#4590

@c-herrewijn
Copy link
Contributor Author

@szarnyasg : can you re-run the CI (for the Lint test)?
I think it should work now with #4590 being merged.

@szarnyasg
Copy link
Collaborator

@c-herrewijn I merged main into your branch and indeed the linter runs now.

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