cognite-sdk-python icon indicating copy to clipboard operation
cognite-sdk-python copied to clipboard

Fix paths in docs & update docs theme

Open MortGron opened this issue 2 years ago • 3 comments

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.transformations etc.
  • 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: image

Example method: image

Example class: image

Example instance object: image

Example mobile view: image

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.

MortGron avatar Jun 20 '23 12:06 MortGron

Codecov Report

Merging #1256 (c5add64) into master (c0c8942) will decrease coverage by 0.58%. The diff coverage is 12.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

... and 1 file with indirect coverage changes

codecov[bot] avatar Jun 20 '23 12:06 codecov[bot]

@erlendvollset have changed the docs source files so that not every class, method etc. have to be explicitly listed.

MortGron avatar Jul 04 '23 21:07 MortGron

@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.

MortGron avatar Aug 25 '23 12:08 MortGron