search

ckan / ckan

CKAN is an open-source DMS (data management system) for powering data hubs and data portals. CKAN makes it easy to publish, share and use data. It powers catalog.data.gov, open.canada.ca/data, data.humdata.org among many other sites.
https://ckan.org/
Other
4.38k stars 1.97k forks source link

package_revise needs more elaboration in the documentation #5787

Open jqnatividad opened 3 years ago

jqnatividad commented 3 years ago

CKAN version 2.9.1

Describe the bug One of the major new features in 2.9 is package_revise. However, there is no guidance/explanation in the documentation as to the advantages of package_revise beyond the API docstring.

Expected behavior There is a note in the changelog with a link to the long PR thread about it (#4618).

Elements of that discussion (e.g. safe to use concurrently unlike other API actions, reusable functions, expanded examples, etc) needs to be added to the documentation beyond the API docstring.

wardi commented 3 years ago

Would love to see better docs around this feature. Is there a better place than the docstring for examples and explanation?

Maybe also expand the API usage examples in the core docs to include a walk through creating, updating, searching and deleting records?

jqnatividad commented 3 years ago

+1 to expanding API usage examples in core docs.

The current examples are a bit "hello world"ish.

Apart from adding more guidance in the core docs, what about an /examples directory?

IMHO, doing so will encourage contributions from the community for reusable "real-world" tools/utilities using the CKAN/Datastore API and other select core tools like ckanapi and scheming (e.g. maintenance scripts, database crawlers using scheming, etc. )

It will also be a good place to move all the examples currently in the /ckanext directory.

mcarans commented 3 years ago

@wardi Is there anything that package_update can do that package_revise can't?

Also, I've raised a related ticket against the CKANAPI Python library as I'm unsure how to pass the various parameters package_revise needs, particularly for file upload, through that library: https://github.com/ckan/ckanapi/issues/181

paulmueller commented 2 years ago

Note that resource upload with the requests library using package_revise is possible and there is a (very custom) example here: https://github.com/ckan/ckan/issues/6360