Update docs on list() and retrieve() to make it clearer to users how to get additional properties specified on views.

[davidaschneider]

Description

Clear up confusion experienced by multiple newcomers to the API about how to retrieve properties specified on a view when using the list() and retrieve() methods in the cognite.client.data_classes.data_modeling.instances API.

There is one statement here that could use some assistance from someone who has a better understanding of what actually happens:

If not specified, only basic fields common to all instances will be retrieved

Any suggests for better wording would be welcome.

Checklist:

• Tests added/updated.
• Documentation updated. Documentation is generated from docstrings - these must be updated according to your change.
  If a new method has been added it should be referenced in cognite.rst in order to generate docs based on its docstring.
• Changelog updated in CHANGELOG.md.
• Version bumped. If triggering a new release is desired, bump the version number in _version.py and pyproject.toml per semantic versioning.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.71%. Comparing base (a9d591a) to head (c58954d).
Report is 3 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2180      +/-   ##
==========================================
+ Coverage   90.65%   90.71%   +0.05%     
==========================================
  Files         159      162       +3     
  Lines       24135    24372     +237     
==========================================
+ Hits        21880    22109     +229     
- Misses       2255     2263       +8     

Files with missing lines	Coverage Δ
cognite/client/_api/data_modeling/instances.py	88.29% <ø> (ø)

... and 6 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[erlendvollset]

Suggested change

sources (Source | Sequence[Source] | None): Governs which views to retrieve properties through. Only properties specified on the provided views will be retrieved. If not specified, only base properties (space, external id, type, ...) will be retrieved. Connection properties (edges and reverse direct properties, see https://docs.cognite.com/cdf/dm/dm_concepts/dm_containers_views_datamodels#connection-properties) can not be retrieved/traversed using this method; use the `query` method instead.

sources (Source | Sequence[Source] | None): Governs which views to retrieve properties through. If not specified, only base properties (space, external id, type, ...) will be retrieved. `Connection properties <https://docs.cognite.com/cdf/dm/dm_concepts/dm_containers_views_datamodels#connection-properties>`_) cannot be retrieved/traversed using this method; use the `query` method instead.

[erlendvollset]

Suggested change

sources (Source | Sequence[Source] | None): Governs which views to retrieve properties through. Only properties specified on the provided views will be retrieved. If not specified, only base properties (space, external id, type, ...) will be retrieved. Connection properties (edges and reverse direct properties, see https://docs.cognite.com/cdf/dm/dm_concepts/dm_containers_views_datamodels#connection-properties) can not be retrieved/traversed using this method; use the `query` method instead.

sources (Source | Sequence[Source] | None): Governs which views to retrieve properties through. If not specified, only base properties (space, external id, type, ...) will be retrieved. `Connection properties <https://docs.cognite.com/cdf/dm/dm_concepts/dm_containers_views_datamodels#connection-properties>`_) cannot be retrieved/traversed using this method; use the `query` method instead.

[erlendvollset]

Requesting input from @arnekv on exact wording here.

[davidaschneider]

As I mentioned on slack to @erlendvollset , the parts he's proposing to remove are parts that would have clarified the problem to newbies like me and Akshat. We sort of understood in principle that we'd only get the properties specified on the view, but actually saying that explicitly in the docs would have made it much clearer to both of us. Likewise, explicitly saying what kinds of properties are not returned (rather than making the user follow a link to a place where they're still not terribly explicit) is much more helpful to the uninitiated.