Fix docs

[bartier]

This PR attempts to close issue #1196

As discussed in the issue, from is a reserved Python keyword, and parameters are passed with from_ to avoid a syntax error. See a example below:

elasticsearch-py/elasticsearch/client/__init__.py

Lines 702 to 704 in 7dec9e3

	# from is a reserved word so it cannot be used, use from_ instead
	if "from_" in params:
	params["from"] = params.pop("from_")

Docs were not rendering the _ underscore character and it would causes a syntax error if you use from instead of from_.

To correcly output underscore character it just needs a \ before it.

Resume of changes:

• Change inside the utils/ directory as all of the code including docstrings under elasticsearch/clients/ is generated from utils/generate_api.py

Hope it helps :)

[elasticmachine]

Since this is a community submitted pull request, a Jenkins build has not been kicked off automatically. Can an Elastic organization member please verify the contents of this patch and then kick off a build manually?

[sethmlarson]

This looks good but let me try with this change locally to ensure the docs are generated properly.

[sethmlarson]

Unfortunately this doesn't work as it doesn't only replace from with from_ in the docstrings. Since we only want this change to be in docstrings we'll need a change within utils/templates/base where docs are generated.

Have you tried running the utils/generate_api.py script? Do a git clone https://github.com/elastic/elasticsearch at the same directory where your elasticsearch-py directory is and then try running the script. Committing the results of the script will be a part of this PR.

Let me know if you have trouble. :)

[bartier]

@sethmlarson Thanks for your reply. I ran successfuly utils/generate_api.py after cloning elasticsearch.

In my understanding, changing only SUBSTITUTIONS = {"type": "doc_type", "from": "from\_"} affects places that should not be changed. (real code for example, instead of documentation, right?)

I could see some changes with my Git UI (GitKraken) after running the script (image below)

I don't understand specifically why the first diff with included in the analysis... appeared. Is that a change that should be there?

The two diffs about from I know it is my change taking effect.

In essence, I need to make it work only with :arg from_: string to replace from word, right?

Thanks for your time and patience. [noob alert here haha]

[sethmlarson]

@bartier Don't worry about the "included with analysis" you shouldn't have to commit any of the changes not related to from\_. Your assessment of which things should change and which should not are correct, we only want docstrings to change. :)

And no worries, I'm here to help you through the process, I really appreciate you taking on this issue :D

[bartier]

@sethmlarson Hi! Is my last commit a valid solution?

I've changed utils/templates/base like you said and committed the results of the script related to 'from'.

A lint error in CI appeared and I'm not sure how should I fix it :/

BTW, this PR commit history is kind of messy. Will my PR be closed automatically by GitHub if I squash all commits to generate only one (and facilitate review code process)? I ask that because my fail PR #1205 looks that this happened.

[sethmlarson]

The lint error can be seen here: https://github.com/elastic/elasticsearch-py/pull/1206/checks?check_run_id=603994279 It is caused by the \ within the docstrings, maybe you can change it to \\? Either that or use r""" for docstring beginnings.

No worries on the commit history, I'll squash all commits to one when merging.

[bartier]

@sethmlarson I escaped \ to fix the lint error.

Can you check it again? :)

PS: Made some mistakes here with my config.email =(

[cla-checker-service]

💚 CLA has been signed

[bartier]

@sethmlarson Now I guess everything is good. I fixed my mistakes with commit history I guess (and PR was not closed automatically haha).

[bartier]

@sethmlarson Is there anything I need to do to keep this going on or something I maybe have done wrong? :)

Thanks

[sethmlarson]

LGTM, thank you!