API guide: Action API reference does not define context

[Chealer]

CKAN's Action API reference lists several functions which require a context parameter, such as

ckan.logic.action.get.package_list(context, data_dict)

It is not explained how to define that parameter.

[wardi]

We're using the sphinx auto documentation feature to expose the API endpoints available, but our internal action functions take their parameters as an internal-only context dict and a user-provided data_dict dict. All the paramters described in the docstrings end up in the internal data_dict parameter.

We could extend sphinx to change the way these parameters appear in the generated documentation to clean this up. Is that something you'd like to help with? There could be another approach to this, but we should keep extracting the API documentation from the action functions so we don't end up with duplicated or outdates docs.

[Chealer]

Thank you wardi, that makes sense. Your proposal seems like a significant job which should ideally be done by someone familiar with the documentation tools (unlike me, who never heard of sphinx), but I agree it is ideal. Since this could take time though, I suggest just adding a warning at the top of the Action API reference section (indicating that these parameters should be ignored).

I agree that extracting documentation from action functions sounds best, if it is possible.