docs: Show correct accessors in the documentation

[MortGron]

Description

Currently the docs does not show how the users access all the methods of the SDK because it shows the methods as beloning to classes the useres do not directly interact with. With this PR the docs will show how the users actually can access the methods of the SDK.

Currently:

Future:

To achieve this, a few changes had to be applied:

• The API methods are now displayed using autosummary. This means all API methods gets its own page in the docs.
• Because of this many docstrings had to be fixed for Sphinx not to throw errors.
• The AsyncCogniteClient has to get the correct accessors. This is only done if a special envionrmental variable is set.

How autosummary looks like:

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.
• The PR title follows the Conventional Commit spec.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.44%. Comparing base (6c915a9) to head (47406ab).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2563      +/-   ##
==========================================
- Coverage   93.47%   93.44%   -0.03%     
==========================================
  Files         478      478              
  Lines       48257    48384     +127     
==========================================
+ Hits        45106    45211     +105     
- Misses       3151     3173      +22     

Files with missing lines	Coverage Δ
cognite/client/_api/agents/agents.py	100.00% <ø> (ø)
cognite/client/_api/ai/tools/documents.py	78.57% <ø> (ø)
cognite/client/_api/annotations.py	95.65% <ø> (ø)
cognite/client/_api/assets.py	97.35% <ø> (ø)
cognite/client/_api/data_modeling/containers.py	98.14% <ø> (ø)
cognite/client/_api/data_modeling/data_models.py	100.00% <ø> (ø)
cognite/client/_api/data_modeling/instances.py	88.55% <ø> (-2.34%)	⬇️
...nite/client/_api/data_modeling/space_statistics.py	100.00% <ø> (ø)
cognite/client/_api/data_modeling/spaces.py	100.00% <ø> (ø)
cognite/client/_api/data_modeling/statistics.py	100.00% <ø> (ø)
... and 121 more

... and 8 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.

[gemini-code-assist]

Code Review

This pull request updates the documentation by standardizing the docstring format for API methods across multiple modules, ensuring they end with a period. It also introduces a new Sphinx extension, sphinx-autosummary-accessors, to improve the documentation of accessors and updates the project configuration to support these documentation improvements.

[erlendvollset]

There's a large amount of formatting changes in the same commit as the main change here, which makes this a lot harder to review than it needs to be. Please split that into a dedicated commit.

The "autosummary and one page per method" setup did not work great the last time we tried it, but will click around a bit tomorrow to see what it's like.

[haakonvt]

Thanks for keeping the PRs coming for docs improvements! While the change in yellow rectangle looks great, I think the change I've marked in the red rectangle is not so great. Can this be modified?

---

[MortGron]

There's a large amount of formatting changes in the same commit as the main change here, which makes this a lot harder to review than it needs to be. Please split that into a dedicated commit.

The "autosummary and one page per method" setup did not work great the last time we tried it, but will click around a bit tomorrow to see what it's like.

This PR has only one goal, and that is to remove the references to the internal classes in the documenation. All other changes are consequences of the way this is achieved. Let me elaborate on this:

• The fundamental approach is to use the package https://sphinx-autosummary-accessors.readthedocs.io/en/stable/ . This is the same approach other major Python packages, like pandas, use to solve the same problem.
• This necceitates the use of autosummary where we have the problem with accessors. Note we do not need to use this for the data classes, as they do already have correct accessors. So this PR does not change the way data classes are doumented.
• When usuing autosummary, Sphinx will throw errors if the summary line of the docstring is a hyperlink with a dot before the link address. This is the main formatting change of dostrings that is needed for Sphinx to not fail.
• In addition, autosummary requires the summary line of dosctrings to not be too long. In particular, docstring that did not have an empty line after the summary line, or that have summary lines of multiple sentences, have been changes to make the autosummary output look accepptable.

What do you mean it did not work great the last time we tried? The major problem with the last attempt was that it had multiple goals, while thie PR only has one goal. I am afraid to not go for this solution, but also not have any clear other solution that solves this problem. I imagine it possible to dig into Sphinx and do more major modifications to achieve correct accessors, but I do not know how to do it, and I am afraid no one else will do it.

[MortGron]

Thanks for keeping the PRs coming for docs improvements! While the change in yellow rectangle looks great, I think the change I've marked in the red rectangle is not so great. Can this be modified?

Thank you for the quick feedback. Is this better? The page heading will end up in the table of contents on the left.

So this is the template showing how the above example was generated. It takes the method name, removes underscores and capitalizes the words.

In particular for this AI section, we should probably make a new heading to indicate this is dealing with documents.

[haakonvt]

@MortGron I'm still not entirely sold on this change - would you mind inviting to a quick 15 min meeting with myself + @erlendvollset and showcase some before and after; what gets better and what potentially gets worse? 😄

[MortGron]

@MortGron I'm still not entirely sold on this change - would you mind inviting to a quick 15 min meeting with myself + @erlendvollset and showcase some before and after; what gets better and what potentially gets worse? 😄

Sold in the sense that you do not want to change the way the accessors are displayed in the documentation, or in the sense that you do not like the side effects of this particular solution?