Fix paths in docs & update docs theme
Description
- Fix paths in documentation so e.g. AsssetsAPI is shown as CogniteClient.assets.
- Update docs theme. New theme have both left and right sidebar and lets one toggle between dark and light mode. Also includes copybutton in code examples.
- Let each class and function have its own stub page. This structure is a consequence of the paths fix.
- Each function and class now uses the summary line in their docstrings in the overview pages in the documentation. Thus there is a need to make sure that the summary lines are of high quality. Various summary lines have been altered in order to e.g. make sure that links are displayed correctly and for improved consistency.
- Make sure year is updated in footer on each build of the docs: "2023, Cognite AS"
- State required Python version on main page. Automatically retrieved from pyproject.toml.
- Make docs dependencies an optional group in pyproject.tom.
- Have links to Cogntie Hub, Academy and Developer Documentation. This should ideally be styled with cogs.js components, but this have not been implemented.
Things to consider
- Whenever a class is made avaible in
cognite.client.data_classes, this is the path shown in the docs. However, there does not seem to be consistency in which classes are avaible there and in e.g.cognite.client.data_classes.transformationsetc. - Because the docs end up with +900 pages, the building time can get long. Thus building with multiple processes have been enabled, and slight optimization of GitHub Actions have been implemented.
- No code in cognite.client is changed, except for when setting up accessors to build the docs. The latter is only done when an enviromental variable is set.
Example topic page:
Example method:
Example class:
Example instance object:
Example mobile view:
Checklist:
- [ ] Tests added/updated.
- [x] 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 Report
Merging #1256 (c5add64) into master (c0c8942) will decrease coverage by
0.58%. The diff coverage is12.79%.
@@ Coverage Diff @@
## master #1256 +/- ##
==========================================
- Coverage 90.42% 89.84% -0.58%
==========================================
Files 110 110
Lines 13515 13595 +80
==========================================
- Hits 12221 12215 -6
- Misses 1294 1380 +86
| Files Changed | Coverage Δ | |
|---|---|---|
| cognite/client/_api/annotations.py | 88.88% <ø> (ø) |
|
| cognite/client/_api/assets.py | 94.87% <ø> (ø) |
|
| cognite/client/_api/data_modeling/containers.py | 83.72% <ø> (ø) |
|
| cognite/client/_api/data_modeling/data_models.py | 82.00% <ø> (ø) |
|
| cognite/client/_api/data_modeling/instances.py | 82.32% <ø> (ø) |
|
| cognite/client/_api/data_modeling/spaces.py | 85.36% <ø> (ø) |
|
| cognite/client/_api/data_modeling/views.py | 86.95% <ø> (ø) |
|
| cognite/client/_api/data_sets.py | 100.00% <ø> (ø) |
|
| cognite/client/_api/datapoints.py | 96.30% <ø> (ø) |
|
| cognite/client/_api/datapoints_subscriptions.py | 100.00% <ø> (ø) |
|
| ... and 30 more |
@erlendvollset have changed the docs source files so that not every class, method etc. have to be explicitly listed.
@cognitedata/python-sdk-maintainers Could someone have a look at this?
This PR will get merge conflicts with master almost inevitable each time master is updated, and also potentially warnings and errors during building of the documentation. The latter because this PR relies heaviliy on autosummary in Sphinx which have more requirements to the formatting of docstrings. Therefore I will not spend time trying to keep this up to date with master unless requested.