[BUG] DSL doesn't seem to be documented, or if it is it's hard to find.

[stuaxo]

If I go to https://pypi.org/project/opensearch-dsl/ it says

Warning

The OpenSearch high-level Python client (opensearch-dsl-py) will be deprecated after version 2.1.0. 

We recommend switching to the OpenSearch Python client (opensearch-py), which now includes the functionality of opensearch-dsl-py.

So on visiting opensearch-py I would expect to see these usages fairly prominently, but it's not obvious at all.

These need to be signposted much better, clicking through to the User Guide, it doesn't look like the query is constructed using the DSL at all, and there is no clue it even exists.

https://github.com/opensearch-project/opensearch-py/blob/main/USER_GUIDE.md

[dblock]

Yes, please contribute.

[stuaxo]

@dblock I don't know what to contribute though:
I didn't write this because I know about the DSL, I want to use it but don't know how because I can't find the docs.

I don't know if the DSL has changed once it got incorporated, or even really where to find the old docs - I'm doing this as a beginner to OpenSearch (but not to DSLs in general)... this seems to have existed at some point, and may still do - I need pointers on where to learn this stuff first.

[dblock]

I hear you @stuaxo. I actually don't know either! I believe the DSL didn't change, we just merged the libraries. Maybe look through https://github.com/opensearch-project/opensearch-py/tree/main/samples and possibly add one and help figure out what we ended up with ;) @saimedhi @VachaShah might know more.

[stuaxocabinetoffice]

I might be wrong, but I assume opensearch-dsl was originally elasticsearch-dsl.

That last one has had docs generated for it.

I didn't have much luck finding them for opensearch-dsl, but maybe nobody ever generated them.

Looking at https://github.com/opensearch-project/opensearch-dsl-py there is a setup.cfg with build-sphinx, just like the one in elasticsearch-py-dsl. They both point at a "docs" directory, but opensearch-dsl has no docs directory.

[dblock]

They both point at a "docs" directory, but opensearch-dsl has no docs directory

It's possible docs didn't make their way into the fork because they were content and not code and may have had licensing problems.

[stuaxo]

Auto generated docs from docstrings could be a good start.

[stuaxocabinetoffice]

They both point at a "docs" directory, but opensearch-dsl has no docs directory

It's possible docs didn't make their way into the fork because they were content and not code and may have had licensing problems.

This may well be the case, given the copyright footer on their docs.

[dblock]

@stuaxo @stuaxocabinetoffice would love some help here! please make PRs