Update guides-bulk example

opensearch-project / opensearch-py

Python Client for OpenSearch

https://opensearch.org/docs/latest/clients/python/

Apache License 2.0

338 stars 170 forks source link

Update guides-bulk example #774

Closed keithrozario closed 2 months ago

keithrozario commented 2 months ago

Fixed examples to make them working python code. (missing commas and quotes.

Description

Example code in the docs were missing crucial commas and double quotes. It meant the code wouldn't run in Python.

While it is a relatively small error that most Python developers will notice it, newcomers might struggle to find the error.

Hope this pull requests makes the example code easier to understand.

Issues Resolved

List any issues this PR will resolve, e.g. Closes [...].

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. For more information on following Developer Certificate of Origin and signing off your commits, please check here.

dblock commented 2 months ago

Thank you!

I assume examples in https://github.com/opensearch-project/opensearch-py/tree/main/samples/bulk do actually run, but if you have a minute please do double-check.

Would love to find a way where the guides are tested, at least for syntax correctness.

dblock commented 2 months ago

Link checker is failing, if you have a second to fix that it'd be amazing!

keithrozario commented 2 months ago

Thanks for merging this.

I looked through the samples before submitting, and at least they don't have this same issue. But not sure about other issues :)
The linkchecker seems a bit odd though, the link in questions seems to work fine. Perhaps its an issue with the runner while the check was running:

keithrozario commented 2 months ago

"Would love to find a way where the guides are tested, at least for syntax correctness."

One thing we could do (and we do for other repos as well) is to move all the code to separate .py files instead of inline in the docs. From there we can lint the .py files to ensure syntax correctness. If it's something the project is looking into, I can perhaps help with that as well.

dblock commented 2 months ago

@keithrozario I think it could be helpful, however I also think people appreciate guides with code snippets in them. We already have working samples. Dunno, maybe it's not worth overthinking.

Another idea is to go the route of https://github.com/opensearch-project/documentation-website/issues/7700 where we generate samples and documentation from spec (https://github.com/opensearch-project/documentation-website/issues/7700), we have these end-to-end tests that run against a real OpenSearch in https://github.com/opensearch-project/opensearch-api-specification/tree/main/tests, they could be turned into working samples and docs mechanically.