Add documentation of query namespaces.

[vyasr]

Description

Add documentation for query filters that combine state point and document keys.

Motivation and Context

Accompanies glotzerlab/signac#332

Checklist:

• I am familiar with the Contributing Guidelines.
• I agree with the terms of the Contributor Agreement.
• My code follows the code style guideline of this project.

[klywang]

This looks clear to me!

[csadorf]

Is using doc_filter arguments then officially deprecated?

[vyasr]

@csadorf I think doc_filter has been around long enough that I don't want to deprecate it in 2.0. I would consider maybe just leaving it undocumented going forward so that new users all switch to the new querying syntax. We could revisit deprecating in 3.0/4.0. Does that sound reasonable?

[bdice]

@vyasr @csadorf I'm not opposed to removing doc_filter in signac 2.0. I don't feel strongly that we should remove it but it would be okay with me if it provided us with maintenance benefits / API unification.

[csadorf]

@vyasr @csadorf I'm not opposed to removing doc_filter in signac 2.0. I don't feel strongly that we should remove it but it would be okay with me if it provided us with maintenance benefits / API unification.

@bdice This is such core API that I think it would present a strong burden for migration. So, if we did this then I would suggest we explore providing some tooling (for example using Bowler) to automatically migrate existing projects. Basically rewrite (doc_filter={'key': 'value'}) to filter={'doc.key': 'value'} in the spirit of 2to3.

[vyasr]

I'm inclined to punt on removing/providing migration tools until a 3.0 release since I do think that it will be a significant migration burden for old scripts. My preference would simply be to preferentially document the new API going forward so that new scripts do not use this, making it more likely that by the time of a 3.0 release the migration would be a much lighter burden since scripts using doc_filter would likely be outdated and unused anyway at that point. We could conceivably deprecate in 2.0 and mark for removal in 3.0, this is the rare case where I would be OK with a deprecation without removal in a major release.