Improve documentation for `import_callback`
- Dominant language
- Jsonnet
- Stars
- 7.6k
- Forks
- 475
- PR merge metrics
- No merged PRs in 30d
Description
I've been struggling to understand how [import_callback](http://jsonnet.org/ref/bindings.html) works using the documentation. It says that it can implement library search paths, which is the functionality I need. The documentation in the old webpage at least discusses what it needs to be called with and returns:
> Another keyword argument import_callback can be used to pass a callable to trap the Jsonnet import constructs. This allows, e.g., reading files out of archives or implementing library search paths. The supplied function must take two string arguments (directory of the current file and the string given to the import construct, which can usually be concatenated to form an actual path but that is up to you). It returns a tuple of two strings, the first being the actual path of the file and the second being the content. The actual path is required so that imports can be resolved within the imported file.
The new page only refers to "see example in python/", which I think(?) refers to [Github](https://github.com/google/jsonnet/tree/master/python). Adding a link would have helped me find that faster. I looked at the example, though, and I still don't understand how to use it to set up library search paths correctly. I tried and failed to use PDB and `print` to figure out what `import_callback` is being called with and what it's returning, but both failed.
I have a layout like:
```
foo.py
jsonnet/
jsonnet/bar.jsonnet
jsonnet/baz.libsonnet
```
`bar.jsonnet` contains `local metadata = import 'baz.libsonnet';`. I want to run `python foo.py`, which contains `_jsonnet.evaluate_snippet` on the contents of `bar.jsonnet` and have the import work correctly.
I tried to have `import_callback` return `jsonnet/` and the contents of `baz.libsonnet`, but I'm still getting import errors, so I've obviously misunderstood. Can someone clarify the documentation, please?
Contributor guide
Assessment
This issue has not been assessed yet.